@useorbits/flags 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# `@useorbits/flags`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Feature flags for apps on [Orbits](https://orbits.africa). Ship code switched off, then turn it on for your team, a
+share of visitors, or everyone, from your project's **Flags** tab, without a redeploy.
+
+Flags are checked in your app, not over the network. The SDK fetches your environment's flags once, answers every
+check from memory, and refreshes them in the background every few seconds, so a change in the Flags tab reaches your
+app within seconds.
+
+## Install
+
+```sh
+npm install @useorbits/flags
+```
+
+Create a flag in your project's **Flags** tab. Orbits gives every deployment its environment's key as `ORBITS_FLAGS`,
+so there's nothing to configure.
+
+## Check a flag
+
+In server code (a Server Component, a route handler, an API, a worker):
+
+```tsx
+import { flag } from "@useorbits/flags";
+
+export default async function Checkout() {
+  const user = await currentUser();
+  if (await flag("new-checkout", { id: user.id, email: user.email })) {
+    return <OnePageCheckout />;
+  }
+  return <ClassicCheckout />;
+}
+```
+
+String and number flags return their value. Pass a default for when the flag doesn't exist yet, or Orbits can't be
+reached:
+
+```ts
+const backend = await flag("search-backend", {}, "typesense");
+const pageSize = await flag("page-size", {}, 20);
+```
+
+A boolean flag's default is `false`.
+
+## Who gets what
+
+What you pass as the second argument is the **context**. Rules in the Flags tab read it, and rollouts use its `id`.
+
+| In the Flags tab | Reads |
+| --- | --- |
+| A rule, such as "Email ends with @kudi.ng" | The context's attribute: `email`, `plan`, `country`, or a path like `user.plan`. Comparisons ignore case. |
+| Rollout to a share of visitors | `id`. The same id always gets the same answer, and stays in as the share grows. Without an id, only a 100% rollout is on. |
+
+For each check, the first matching rule decides. Otherwise a boolean flag is off when it's switched off, and on for
+its rollout's share of ids when it's on. A string or number flag serves its value.
+
+To get every flag at once, such as to pass them all to a page:
+
+```ts
+import { flags } from "@useorbits/flags";
+
+const all = await flags({ id: user.id });
+// { "new-checkout": true, "search-backend": "typesense" }
+```
+
+## Environments
+
+Each deployment reads its own environment: production deployments get Production's flags, previews get Preview's.
+
+To use Development's flags on your machine, copy its key from the Flags tab into `.env.local`:
+
+```sh
+ORBITS_FLAGS=ofl_…
+```
+
+Without a key, every flag gets its default, and the SDK says so once in the console.
+
+## Options
+
+The shared client reads `ORBITS_FLAGS` and `ORBITS_API_URL`. To set them yourself, call `configure` before the first
+check:
+
+```ts
+import { configure } from "@useorbits/flags";
+
+configure({ key: process.env.MY_FLAGS_KEY, refreshMs: 10_000 });
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `key` | `ORBITS_FLAGS` | The environment's key. |
+| `apiUrl` | `ORBITS_API_URL` | Orbits' API. |
+| `refreshMs` | `5000` | How old the flags may get before they're fetched again in the background. |
+| `report` | `true` | Report which flags were checked, for the Flags tab's "Seen in the last 24 hours". |
+| `debug` | `false` | Log fetches and reports. |
+
+For more than one key in a process, make a client of your own: `new FlagsClient({ key })`, then `client.flag(...)`.
+
+## What's reported
+
+About once a minute while flags are being checked, the SDK tells Orbits how often each flag was checked and for which
+ids. Each id goes as the first 16 characters of its SHA-256, never as it was. Turn it off with
+`configure({ report: false })`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,216 @@
+"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);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  FlagsClient: () => FlagsClient,
+  bucket: () => bucket,
+  configure: () => configure,
+  evaluate: () => evaluate,
+  flag: () => flag,
+  flags: () => flags,
+  matches: () => matches
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/evaluate.ts
+function read(context, attribute) {
+  let at = context;
+  for (const part of attribute.split(".")) {
+    if (at === null || typeof at !== "object") return void 0;
+    at = at[part];
+  }
+  return at;
+}
+function matches(rule, context) {
+  const raw = read(context, rule.attribute);
+  if (raw === void 0 || raw === null || typeof raw === "object") return false;
+  const value = String(raw).toLowerCase();
+  const values = rule.values.map((v) => v.toLowerCase());
+  const first = values[0] ?? "";
+  switch (rule.operator) {
+    case "equals":
+      return value === first;
+    case "not_equals":
+      return value !== first;
+    case "one_of":
+      return values.includes(value);
+    case "ends_with":
+      return value.endsWith(first);
+    case "starts_with":
+      return value.startsWith(first);
+    case "contains":
+      return value.includes(first);
+  }
+}
+function bucket(key, id) {
+  let hash = 2166136261;
+  for (const ch of `${key}:${id}`) {
+    hash ^= ch.codePointAt(0);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % 100;
+}
+function evaluate(key, def, context = {}) {
+  for (const rule of def.rules) if (matches(rule, context)) return rule.serve;
+  if (def.type !== "boolean") return def.value ?? (def.type === "number" ? 0 : "");
+  if (!def.on) return false;
+  if (def.rollout >= 100) return true;
+  const id = context.id;
+  if (id === void 0 || id === null || id === "") return false;
+  return bucket(key, String(id)) < def.rollout;
+}
+
+// src/client.ts
+var DEFAULT_API = "https://api.theorbits.app";
+var REPORT_EVERY = 6e4;
+var IDS_PER_FLAG = 500;
+var TIMEOUT = 3e3;
+var env = (name) => typeof process === "undefined" ? void 0 : process.env[name];
+async function hashId(id) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id));
+  return [...new Uint8Array(digest).slice(0, 8)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var FlagsClient = class {
+  constructor(options = {}) {
+    this.current = null;
+    this.fetchedAt = 0;
+    this.loading = null;
+    this.warned = false;
+    this.checks = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.key = options.key ?? env("ORBITS_FLAGS");
+    this.api = (options.apiUrl ?? env("ORBITS_API_URL") ?? DEFAULT_API).replace(/\/+$/, "");
+    this.refreshMs = options.refreshMs ?? 5e3;
+    this.report = options.report ?? true;
+    this.debug = options.debug ?? false;
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  log(...args) {
+    if (this.debug) console.info("[Orbits Flags]", ...args);
+  }
+  /** Fetches the flags, or confirms the ones held are current; keeps them when Orbits can't be reached. */
+  load() {
+    this.loading ?? (this.loading = (async () => {
+      try {
+        const res = await this.fetch(`${this.api}/v1/flags/definitions`, {
+          headers: { authorization: `Bearer ${this.key}`, ...this.current ? { "if-none-match": `"${this.current.version}"` } : {} },
+          cache: "no-store",
+          signal: AbortSignal.timeout(TIMEOUT)
+        });
+        if (res.status === 304) this.log("unchanged");
+        else if (res.ok) {
+          this.current = await res.json();
+          this.log(`fetched ${Object.keys(this.current.flags).length} flags for ${this.current.environment}`);
+        } else if (!this.warned) {
+          this.warned = true;
+          console.warn(`[Orbits Flags] Orbits answered ${res.status} for the flags; checks get their defaults until it doesn't.`);
+        }
+        this.fetchedAt = Date.now();
+      } catch (error) {
+        this.log("couldn't reach Orbits", error);
+        this.fetchedAt = Date.now();
+      } finally {
+        this.loading = null;
+      }
+    })());
+    return this.loading;
+  }
+  /** The environment's flags: fetched the first time, then served from memory and refreshed behind the scenes. */
+  async definitions() {
+    if (!this.key) {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("[Orbits Flags] ORBITS_FLAGS isn't set, so every flag gets its default. Orbits sets it on deployments; locally, copy Development's key from the Flags page into .env.local.");
+      }
+      return null;
+    }
+    if (!this.current) await this.load();
+    else if (Date.now() - this.fetchedAt > this.refreshMs) void this.load();
+    return this.current;
+  }
+  /** A flag's value for this context, or the default when Orbits has no such flag (or couldn't be reached). */
+  async flag(key, context = {}, defaultValue) {
+    const fallback = defaultValue ?? false;
+    const defs = await this.definitions();
+    const def = defs?.flags[key];
+    if (!def) return fallback;
+    this.count(key, context.id);
+    return evaluate(key, def, context);
+  }
+  /** Every flag's value for this context, such as to hand a page all it needs at once. */
+  async all(context = {}) {
+    const defs = await this.definitions();
+    if (!defs) return {};
+    return Object.fromEntries(Object.entries(defs.flags).map(([key, def]) => [key, evaluate(key, def, context)]));
+  }
+  count(key, id) {
+    if (!this.report) return;
+    const c = this.checks.get(key) ?? { count: 0, ids: /* @__PURE__ */ new Set() };
+    c.count++;
+    if (id !== void 0 && id !== null && id !== "" && c.ids.size < IDS_PER_FLAG) c.ids.add(String(id));
+    this.checks.set(key, c);
+    if (!this.timer) {
+      this.timer = setInterval(() => void this.flush(), REPORT_EVERY);
+      this.timer.unref?.();
+    }
+  }
+  /** Sends what was checked since the last report. Called every minute while flags are checked. */
+  async flush() {
+    if (!this.key || !this.checks.size) return;
+    const batch = [...this.checks].slice(0, 200);
+    for (const [key] of batch) this.checks.delete(key);
+    const flags2 = await Promise.all(batch.map(async ([key, c]) => ({ key, checks: c.count, ids: await Promise.all([...c.ids].map(hashId)) })));
+    try {
+      await this.fetch(`${this.api}/v1/flags/exposures`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
+        body: JSON.stringify({ flags: flags2 }),
+        signal: AbortSignal.timeout(TIMEOUT)
+      });
+      this.log(`reported ${flags2.length} flags`);
+    } catch (error) {
+      this.log("couldn't report checks", error);
+    }
+  }
+};
+
+// src/index.ts
+var shared = null;
+var client = () => shared ?? (shared = new FlagsClient());
+function flag(key, context, defaultValue) {
+  return client().flag(key, context, defaultValue);
+}
+function flags(context) {
+  return client().all(context);
+}
+function configure(options) {
+  shared = new FlagsClient(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagsClient,
+  bucket,
+  configure,
+  evaluate,
+  flag,
+  flags,
+  matches
+});

package/dist/index.d.cts

@@ -0,0 +1,88 @@
+type FlagValue = boolean | string | number;
+/** What a rule can read: an id for rollouts, and anything else to target on (email, plan, user.country). */
+type FlagContext = {
+    id?: string | number | null;
+    [attribute: string]: unknown;
+};
+type RuleOperator = "equals" | "not_equals" | "one_of" | "ends_with" | "starts_with" | "contains";
+interface Rule {
+    attribute: string;
+    operator: RuleOperator;
+    values: string[];
+    serve: FlagValue;
+}
+interface Definition {
+    type: "boolean" | "string" | "number";
+    on: boolean;
+    rollout: number;
+    value: string | number | null;
+    rules: Rule[];
+}
+/** Comparisons ignore case: an email's domain is the same whatever the visitor typed. */
+declare function matches(rule: Rule, context: FlagContext): boolean;
+/** 0–99, the same for a flag and an id every time (32-bit FNV-1a), so a visitor stays in or out as a rollout grows. */
+declare function bucket(key: string, id: string): number;
+declare function evaluate(key: string, def: Definition, context?: FlagContext): FlagValue;
+
+interface FlagsOptions {
+    /** The environment's key: ORBITS_FLAGS, which Orbits sets on every deployment. */
+    key?: string;
+    /** Orbits' API: ORBITS_API_URL, set beside it. */
+    apiUrl?: string;
+    /** How old the flags may get before they're fetched again in the background, in ms (5 seconds). */
+    refreshMs?: number;
+    /** Report which flags were checked, for the flag's "Seen in the last 24 hours" (on unless false). */
+    report?: boolean;
+    /** Log fetches and reports. */
+    debug?: boolean;
+    fetch?: typeof fetch;
+}
+type Definitions = {
+    environment: string;
+    version: string;
+    flags: Record<string, Definition>;
+};
+declare class FlagsClient {
+    private readonly key;
+    private readonly api;
+    private readonly refreshMs;
+    private readonly report;
+    private readonly debug;
+    private readonly fetch;
+    private current;
+    private fetchedAt;
+    private loading;
+    private warned;
+    private readonly checks;
+    private timer;
+    constructor(options?: FlagsOptions);
+    private log;
+    /** Fetches the flags, or confirms the ones held are current; keeps them when Orbits can't be reached. */
+    private load;
+    /** The environment's flags: fetched the first time, then served from memory and refreshed behind the scenes. */
+    definitions(): Promise<Definitions | null>;
+    /** A flag's value for this context, or the default when Orbits has no such flag (or couldn't be reached). */
+    flag<T extends FlagValue = boolean>(key: string, context?: FlagContext, defaultValue?: T): Promise<T>;
+    /** Every flag's value for this context, such as to hand a page all it needs at once. */
+    all(context?: FlagContext): Promise<Record<string, FlagValue>>;
+    private count;
+    /** Sends what was checked since the last report. Called every minute while flags are checked. */
+    flush(): Promise<void>;
+}
+
+/**
+ * A flag's value, in server code: on, off or its value in this deployment's environment, for this context. Rules
+ * read the context (`email`, `plan`, `user.country`), rollouts its `id`. Without such a flag, or before Orbits can be
+ * reached, it's the default: false unless you pass one.
+ *
+ *     if (await flag("new-checkout", { id: user.id, email: user.email })) return <OnePageCheckout />;
+ *     const backend = await flag("search-backend", {}, "typesense");
+ */
+declare function flag<T extends FlagValue = boolean>(key: string, context?: FlagContext, defaultValue?: T): Promise<T>;
+/** Every flag's value for this context at once. */
+declare function flags(context?: FlagContext): Promise<Record<string, FlagValue>>;
+/** Sets how the shared client reads flags; call before the first flag(). Without it, it reads ORBITS_FLAGS. */
+declare function configure(options: FlagsOptions): void;
+
+export { FlagsClient, bucket, configure, evaluate, flag, flags, matches };
+export type { Definition, FlagContext, FlagValue, FlagsOptions, Rule, RuleOperator };

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+type FlagValue = boolean | string | number;
+/** What a rule can read: an id for rollouts, and anything else to target on (email, plan, user.country). */
+type FlagContext = {
+    id?: string | number | null;
+    [attribute: string]: unknown;
+};
+type RuleOperator = "equals" | "not_equals" | "one_of" | "ends_with" | "starts_with" | "contains";
+interface Rule {
+    attribute: string;
+    operator: RuleOperator;
+    values: string[];
+    serve: FlagValue;
+}
+interface Definition {
+    type: "boolean" | "string" | "number";
+    on: boolean;
+    rollout: number;
+    value: string | number | null;
+    rules: Rule[];
+}
+/** Comparisons ignore case: an email's domain is the same whatever the visitor typed. */
+declare function matches(rule: Rule, context: FlagContext): boolean;
+/** 0–99, the same for a flag and an id every time (32-bit FNV-1a), so a visitor stays in or out as a rollout grows. */
+declare function bucket(key: string, id: string): number;
+declare function evaluate(key: string, def: Definition, context?: FlagContext): FlagValue;
+
+interface FlagsOptions {
+    /** The environment's key: ORBITS_FLAGS, which Orbits sets on every deployment. */
+    key?: string;
+    /** Orbits' API: ORBITS_API_URL, set beside it. */
+    apiUrl?: string;
+    /** How old the flags may get before they're fetched again in the background, in ms (5 seconds). */
+    refreshMs?: number;
+    /** Report which flags were checked, for the flag's "Seen in the last 24 hours" (on unless false). */
+    report?: boolean;
+    /** Log fetches and reports. */
+    debug?: boolean;
+    fetch?: typeof fetch;
+}
+type Definitions = {
+    environment: string;
+    version: string;
+    flags: Record<string, Definition>;
+};
+declare class FlagsClient {
+    private readonly key;
+    private readonly api;
+    private readonly refreshMs;
+    private readonly report;
+    private readonly debug;
+    private readonly fetch;
+    private current;
+    private fetchedAt;
+    private loading;
+    private warned;
+    private readonly checks;
+    private timer;
+    constructor(options?: FlagsOptions);
+    private log;
+    /** Fetches the flags, or confirms the ones held are current; keeps them when Orbits can't be reached. */
+    private load;
+    /** The environment's flags: fetched the first time, then served from memory and refreshed behind the scenes. */
+    definitions(): Promise<Definitions | null>;
+    /** A flag's value for this context, or the default when Orbits has no such flag (or couldn't be reached). */
+    flag<T extends FlagValue = boolean>(key: string, context?: FlagContext, defaultValue?: T): Promise<T>;
+    /** Every flag's value for this context, such as to hand a page all it needs at once. */
+    all(context?: FlagContext): Promise<Record<string, FlagValue>>;
+    private count;
+    /** Sends what was checked since the last report. Called every minute while flags are checked. */
+    flush(): Promise<void>;
+}
+
+/**
+ * A flag's value, in server code: on, off or its value in this deployment's environment, for this context. Rules
+ * read the context (`email`, `plan`, `user.country`), rollouts its `id`. Without such a flag, or before Orbits can be
+ * reached, it's the default: false unless you pass one.
+ *
+ *     if (await flag("new-checkout", { id: user.id, email: user.email })) return <OnePageCheckout />;
+ *     const backend = await flag("search-backend", {}, "typesense");
+ */
+declare function flag<T extends FlagValue = boolean>(key: string, context?: FlagContext, defaultValue?: T): Promise<T>;
+/** Every flag's value for this context at once. */
+declare function flags(context?: FlagContext): Promise<Record<string, FlagValue>>;
+/** Sets how the shared client reads flags; call before the first flag(). Without it, it reads ORBITS_FLAGS. */
+declare function configure(options: FlagsOptions): void;
+
+export { FlagsClient, bucket, configure, evaluate, flag, flags, matches };
+export type { Definition, FlagContext, FlagValue, FlagsOptions, Rule, RuleOperator };

package/dist/index.js

@@ -0,0 +1,183 @@
+// src/evaluate.ts
+function read(context, attribute) {
+  let at = context;
+  for (const part of attribute.split(".")) {
+    if (at === null || typeof at !== "object") return void 0;
+    at = at[part];
+  }
+  return at;
+}
+function matches(rule, context) {
+  const raw = read(context, rule.attribute);
+  if (raw === void 0 || raw === null || typeof raw === "object") return false;
+  const value = String(raw).toLowerCase();
+  const values = rule.values.map((v) => v.toLowerCase());
+  const first = values[0] ?? "";
+  switch (rule.operator) {
+    case "equals":
+      return value === first;
+    case "not_equals":
+      return value !== first;
+    case "one_of":
+      return values.includes(value);
+    case "ends_with":
+      return value.endsWith(first);
+    case "starts_with":
+      return value.startsWith(first);
+    case "contains":
+      return value.includes(first);
+  }
+}
+function bucket(key, id) {
+  let hash = 2166136261;
+  for (const ch of `${key}:${id}`) {
+    hash ^= ch.codePointAt(0);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % 100;
+}
+function evaluate(key, def, context = {}) {
+  for (const rule of def.rules) if (matches(rule, context)) return rule.serve;
+  if (def.type !== "boolean") return def.value ?? (def.type === "number" ? 0 : "");
+  if (!def.on) return false;
+  if (def.rollout >= 100) return true;
+  const id = context.id;
+  if (id === void 0 || id === null || id === "") return false;
+  return bucket(key, String(id)) < def.rollout;
+}
+
+// src/client.ts
+var DEFAULT_API = "https://api.theorbits.app";
+var REPORT_EVERY = 6e4;
+var IDS_PER_FLAG = 500;
+var TIMEOUT = 3e3;
+var env = (name) => typeof process === "undefined" ? void 0 : process.env[name];
+async function hashId(id) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id));
+  return [...new Uint8Array(digest).slice(0, 8)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var FlagsClient = class {
+  constructor(options = {}) {
+    this.current = null;
+    this.fetchedAt = 0;
+    this.loading = null;
+    this.warned = false;
+    this.checks = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.key = options.key ?? env("ORBITS_FLAGS");
+    this.api = (options.apiUrl ?? env("ORBITS_API_URL") ?? DEFAULT_API).replace(/\/+$/, "");
+    this.refreshMs = options.refreshMs ?? 5e3;
+    this.report = options.report ?? true;
+    this.debug = options.debug ?? false;
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  log(...args) {
+    if (this.debug) console.info("[Orbits Flags]", ...args);
+  }
+  /** Fetches the flags, or confirms the ones held are current; keeps them when Orbits can't be reached. */
+  load() {
+    this.loading ?? (this.loading = (async () => {
+      try {
+        const res = await this.fetch(`${this.api}/v1/flags/definitions`, {
+          headers: { authorization: `Bearer ${this.key}`, ...this.current ? { "if-none-match": `"${this.current.version}"` } : {} },
+          cache: "no-store",
+          signal: AbortSignal.timeout(TIMEOUT)
+        });
+        if (res.status === 304) this.log("unchanged");
+        else if (res.ok) {
+          this.current = await res.json();
+          this.log(`fetched ${Object.keys(this.current.flags).length} flags for ${this.current.environment}`);
+        } else if (!this.warned) {
+          this.warned = true;
+          console.warn(`[Orbits Flags] Orbits answered ${res.status} for the flags; checks get their defaults until it doesn't.`);
+        }
+        this.fetchedAt = Date.now();
+      } catch (error) {
+        this.log("couldn't reach Orbits", error);
+        this.fetchedAt = Date.now();
+      } finally {
+        this.loading = null;
+      }
+    })());
+    return this.loading;
+  }
+  /** The environment's flags: fetched the first time, then served from memory and refreshed behind the scenes. */
+  async definitions() {
+    if (!this.key) {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("[Orbits Flags] ORBITS_FLAGS isn't set, so every flag gets its default. Orbits sets it on deployments; locally, copy Development's key from the Flags page into .env.local.");
+      }
+      return null;
+    }
+    if (!this.current) await this.load();
+    else if (Date.now() - this.fetchedAt > this.refreshMs) void this.load();
+    return this.current;
+  }
+  /** A flag's value for this context, or the default when Orbits has no such flag (or couldn't be reached). */
+  async flag(key, context = {}, defaultValue) {
+    const fallback = defaultValue ?? false;
+    const defs = await this.definitions();
+    const def = defs?.flags[key];
+    if (!def) return fallback;
+    this.count(key, context.id);
+    return evaluate(key, def, context);
+  }
+  /** Every flag's value for this context, such as to hand a page all it needs at once. */
+  async all(context = {}) {
+    const defs = await this.definitions();
+    if (!defs) return {};
+    return Object.fromEntries(Object.entries(defs.flags).map(([key, def]) => [key, evaluate(key, def, context)]));
+  }
+  count(key, id) {
+    if (!this.report) return;
+    const c = this.checks.get(key) ?? { count: 0, ids: /* @__PURE__ */ new Set() };
+    c.count++;
+    if (id !== void 0 && id !== null && id !== "" && c.ids.size < IDS_PER_FLAG) c.ids.add(String(id));
+    this.checks.set(key, c);
+    if (!this.timer) {
+      this.timer = setInterval(() => void this.flush(), REPORT_EVERY);
+      this.timer.unref?.();
+    }
+  }
+  /** Sends what was checked since the last report. Called every minute while flags are checked. */
+  async flush() {
+    if (!this.key || !this.checks.size) return;
+    const batch = [...this.checks].slice(0, 200);
+    for (const [key] of batch) this.checks.delete(key);
+    const flags2 = await Promise.all(batch.map(async ([key, c]) => ({ key, checks: c.count, ids: await Promise.all([...c.ids].map(hashId)) })));
+    try {
+      await this.fetch(`${this.api}/v1/flags/exposures`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
+        body: JSON.stringify({ flags: flags2 }),
+        signal: AbortSignal.timeout(TIMEOUT)
+      });
+      this.log(`reported ${flags2.length} flags`);
+    } catch (error) {
+      this.log("couldn't report checks", error);
+    }
+  }
+};
+
+// src/index.ts
+var shared = null;
+var client = () => shared ?? (shared = new FlagsClient());
+function flag(key, context, defaultValue) {
+  return client().flag(key, context, defaultValue);
+}
+function flags(context) {
+  return client().all(context);
+}
+function configure(options) {
+  shared = new FlagsClient(options);
+}
+export {
+  FlagsClient,
+  bucket,
+  configure,
+  evaluate,
+  flag,
+  flags,
+  matches
+};

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@useorbits/flags",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Feature flags for apps on Orbits: switch code on for your team, a share of visitors or everyone, without a redeploy.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/The-Orbits/insights.git", "directory": "packages/flags" },
+  "homepage": "https://orbits.africa",
+  "keywords": ["feature flags", "flags", "rollout", "orbits"],
+  "type": "module",
+  "sideEffects": false,
+  "files": ["dist"],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "publishConfig": { "access": "public", "provenance": true }
+}