@adonis-agora/flags 0.0.0-beta-20261112141227

package/dist/src/enrichers.js

@@ -0,0 +1,105 @@
+import { channel } from 'node:diagnostics_channel';
+/** Channel names, following the ecosystem's `agora:<lib>:<event>` convention. */
+export const DIAGNOSTICS_CHANNELS = {
+    evaluation: 'agora:flags:evaluation',
+    exposure: 'agora:flags:exposure',
+    track: 'agora:flags:track',
+    change: 'agora:flags:change',
+};
+export const enrichers = {
+    /**
+     * Publishes evaluations, exposures and tracks on `node:diagnostics_channel` (`agora:flags:*`):
+     * `@adonis-agora/diagnostics` and telescope pick them up. Free when nobody subscribes.
+     */
+    diagnostics() {
+        const evaluation = channel(DIAGNOSTICS_CHANNELS.evaluation);
+        const exposure = channel(DIAGNOSTICS_CHANNELS.exposure);
+        const track = channel(DIAGNOSTICS_CHANNELS.track);
+        return {
+            name: 'diagnostics',
+            onEvaluation(details, context) {
+                if (evaluation.hasSubscribers) {
+                    evaluation.publish({
+                        flag: details.flagKey,
+                        variant: details.variant,
+                        reason: details.reason,
+                        errorCode: details.errorCode,
+                        subject: context.targetingKey,
+                    });
+                }
+            },
+            onEvent(event) {
+                const target = event.type === 'exposure' ? exposure : track;
+                if (target.hasSubscribers)
+                    target.publish(event);
+            },
+        };
+    },
+    /**
+     * OpenTelemetry: a `feature_flag.evaluation` event on the active span, with the semantic
+     * convention attributes (`feature_flag.key`, `feature_flag.result.variant`, …). Needs
+     * `@opentelemetry/api` (optional peer); without it this enricher does nothing.
+     */
+    otel() {
+        let api;
+        return {
+            name: 'otel',
+            async setup() {
+                try {
+                    api = (await import('@opentelemetry/api'));
+                }
+                catch {
+                    api = undefined;
+                }
+            },
+            onEvaluation(details, context) {
+                const span = api?.trace.getActiveSpan();
+                if (!span)
+                    return;
+                span.addEvent('feature_flag.evaluation', {
+                    'feature_flag.key': details.flagKey,
+                    'feature_flag.provider.name': '@adonis-agora/flags',
+                    'feature_flag.result.variant': details.variant,
+                    'feature_flag.result.reason': details.reason.toLowerCase(),
+                    ...(details.errorCode ? { 'error.type': details.errorCode.toLowerCase() } : {}),
+                    ...(context.targetingKey ? { 'feature_flag.context.id': context.targetingKey } : {}),
+                    ...(typeof details.flagMetadata.rulesetVersion === 'string'
+                        ? { 'feature_flag.version': details.flagMetadata.rulesetVersion }
+                        : {}),
+                });
+            },
+        };
+    },
+    /**
+     * Sentry: records each evaluated flag on the current scope, so an error report lists the flags
+     * the request saw. Pass your Sentry module: `enrichers.sentry(Sentry)`. Uses Sentry's
+     * feature-flags integration when it is installed, and a `flag.<key>` tag otherwise.
+     */
+    sentry(sentry) {
+        return {
+            name: 'sentry',
+            onEvaluation(details) {
+                const integration = sentry.getClient?.()?.getIntegrationByName?.('FeatureFlags');
+                if (integration?.addFeatureFlag) {
+                    integration.addFeatureFlag(details.flagKey, details.value);
+                    return;
+                }
+                sentry
+                    .getCurrentScope?.()
+                    ?.setTag?.(`flag.${details.flagKey}`, String(details.variant ?? details.value));
+            },
+        };
+    },
+};
+/** Runs enrichers without ever letting one break evaluation. */
+export function runEnrichers(list, fn) {
+    for (const enricher of list) {
+        try {
+            fn(enricher);
+        }
+        catch {
+            // Enrichers are best-effort by contract.
+        }
+    }
+}
+//# sourceMappingURL=enrichers.js.map

package/dist/src/enrichers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichers.js","sourceRoot":"","sources":["../../src/enrichers.ts"],"names":[],"mappings":"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"}

package/dist/src/events/buffer.d.ts

@@ -0,0 +1,38 @@
+import type { Transport } from '../transports/transport.js';
+import type { FlagEvent } from './event.js';
+export interface BufferOptions {
+    /** Flush when this many events are waiting. Default 500. */
+    maxSize?: number;
+    /** Flush at least this often (ms). Default 1000. */
+    flushMs?: number;
+    /**
+     * Hard cap while the transport is failing. Beyond it the OLDEST events are dropped (and counted)
+     * so a long outage cannot exhaust memory. Default 50,000.
+     */
+    maxQueue?: number;
+    /** Exposure ids remembered to skip repeats in this process. Default 100,000. */
+    dedupeSize?: number;
+    onError?: (error: unknown) => void;
+}
+/**
+ * Batches events in process before they reach the transport, so a busy page does not turn into
+ * one INSERT per exposure. Exposures are also deduped here: the same subject seeing the same
+ * experiment on every request produces one event per process, not one per request (the sinks
+ * dedupe the rest).
+ */
+export declare class EventBuffer {
+    #private;
+    private readonly transport;
+    private readonly options;
+    dropped: number;
+    published: number;
+    constructor(transport: Transport, options?: BufferOptions);
+    start(): void;
+    /** Queues an event. Returns `false` for an exposure this process already sent. */
+    push(event: FlagEvent): boolean;
+    get pending(): number;
+    flush(): Promise<void>;
+    /** Stops the timer and sends what is left. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=buffer.d.ts.map

package/dist/src/events/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../../src/events/buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,WAAW;;IASpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,SAAK;IACZ,SAAS,SAAK;IAEd,YACmB,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,aAAkB,EAC1C;IAEJ,KAAK,SAGJ;IAED,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAuB9B;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrB;IAmBD,8CAA8C;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3B;CACF"}

package/dist/src/events/buffer.js

@@ -0,0 +1,86 @@
+/**
+ * Batches events in process before they reach the transport, so a busy page does not turn into
+ * one INSERT per exposure. Exposures are also deduped here: the same subject seeing the same
+ * experiment on every request produces one event per process, not one per request (the sinks
+ * dedupe the rest).
+ */
+export class EventBuffer {
+    transport;
+    options;
+    #queue = [];
+    #timer;
+    #flushing;
+    #seen = new Map();
+    dropped = 0;
+    published = 0;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.options = options;
+    }
+    start() {
+        this.#timer ??= setInterval(() => void this.flush(), this.options.flushMs ?? 1000);
+        this.#timer.unref();
+    }
+    /** Queues an event. Returns `false` for an exposure this process already sent. */
+    push(event) {
+        if (event.type === 'exposure') {
+            if (this.#seen.has(event.id))
+                return false;
+            this.#seen.set(event.id, true);
+            const cap = this.options.dedupeSize ?? 100_000;
+            if (this.#seen.size > cap) {
+                // Map iteration order is insertion order: drop the oldest tenth.
+                let drop = Math.ceil(cap / 10);
+                for (const key of this.#seen.keys()) {
+                    this.#seen.delete(key);
+                    if (--drop === 0)
+                        break;
+                }
+            }
+        }
+        this.#queue.push(event);
+        const maxQueue = this.options.maxQueue ?? 50_000;
+        if (this.#queue.length > maxQueue) {
+            const excess = this.#queue.length - maxQueue;
+            this.#queue.splice(0, excess);
+            this.dropped += excess;
+        }
+        if (this.#queue.length >= (this.options.maxSize ?? 500))
+            void this.flush();
+        return true;
+    }
+    get pending() {
+        return this.#queue.length;
+    }
+    flush() {
+        this.#flushing ??= this.#flush().finally(() => {
+            this.#flushing = undefined;
+        });
+        return this.#flushing;
+    }
+    async #flush() {
+        while (this.#queue.length > 0) {
+            const batch = this.#queue.slice(0, this.options.maxSize ?? 500);
+            const droppedBefore = this.dropped;
+            try {
+                await this.transport.publish(batch);
+            }
+            catch (error) {
+                // Keep the batch for the next tick; the transport may be back by then.
+                this.options.onError?.(error);
+                return;
+            }
+            // Overflow while publishing drops from the front, i.e. from this batch first.
+            this.#queue.splice(0, Math.max(0, batch.length - (this.dropped - droppedBefore)));
+            this.published += batch.length;
+        }
+    }
+    /** Stops the timer and sends what is left. */
+    async close() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = undefined;
+        await this.flush();
+    }
+}
+//# sourceMappingURL=buffer.js.map

package/dist/src/events/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../../src/events/buffer.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IASH,SAAS;IACT,OAAO;IAT1B,MAAM,GAAgB,EAAE,CAAC;IACzB,MAAM,CAA6B;IACnC,SAAS,CAA4B;IACrC,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAChC,OAAO,GAAG,CAAC,CAAC;IACZ,SAAS,GAAG,CAAC,CAAC;IAEd,YACmB,SAAoB,EACpB,OAAO,GAAkB,EAAE;yBAD3B,SAAS;uBACT,OAAO;IACvB,CAAC;IAEJ,KAAK;QACH,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACnF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,kFAAkF;IAClF,IAAI,CAAC,KAAgB;QACnB,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC3C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC;YAC/C,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC;gBAC1B,iEAAiE;gBACjE,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;gBAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;oBACpC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACvB,IAAI,EAAE,IAAI,KAAK,CAAC;wBAAE,MAAM;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC;QACjD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC9B,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC;QACzB,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;YAAE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC5C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;YAChE,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACtC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,uEAAuE;gBACvE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,8EAA8E;YAC9E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAClF,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;QACjC,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/src/events/event.d.ts

@@ -0,0 +1,42 @@
+/** Version of the event contract below. Bumped only for incompatible changes. */
+export declare const EVENT_SCHEMA_VERSION = 1;
+/**
+ * The one event shape every transport and sink speaks (DESIGN §7). Timestamps are epoch
+ * milliseconds so every backend (Postgres, MySQL, SQLite, DuckDB, ClickHouse) compares them as
+ * plain numbers.
+ */
+export interface FlagEvent {
+    /** UUID. Exposures use a deterministic id per (experiment, subject) so re-sends dedupe. */
+    id: string;
+    schemaVersion: number;
+    /** The app that produced it (a tenant's `partition`, or the standalone app name). */
+    app: string;
+    /** The environment whose ruleset assigned it (`production`, `staging`, …). */
+    environment: string;
+    type: 'exposure' | 'track';
+    /** Exposure: the flag. Track: absent. */
+    flag?: string;
+    /** Exposure: the experiment key. */
+    experiment?: string;
+    /** Exposure: the variant served. */
+    variant?: string;
+    /** Track: the event name (`purchase`, `signup`). */
+    name?: string;
+    subject: string;
+    subjectType: string;
+    /** Track: the numeric value (revenue, duration). */
+    value?: number;
+    props?: Record<string, unknown>;
+    /** Epoch milliseconds. */
+    ts: number;
+}
+/** A UUIDv7: time-ordered, so ids sort roughly by creation in every store. */
+export declare function uuidv7(now?: number): string;
+/**
+ * The id of the exposure of `subject` to `experiment`: a UUIDv5-style hash, identical on every
+ * send, so a destination that dedupes by id keeps one row however often the relay retries.
+ */
+export declare function exposureId(app: string, environment: string, experiment: string, subject: string): string;
+/** Light structural validation for events arriving over HTTP from a tenant. */
+export declare function parseEvents(input: unknown, app: string, environment: string): FlagEvent[];
+//# sourceMappingURL=event.d.ts.map

package/dist/src/events/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/events/event.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,8EAA8E;AAC9E,wBAAgB,MAAM,CAAC,GAAG,SAAa,GAAG,MAAM,CAY/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,MAAM,CAQR;AAOD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,CAyCzF"}

package/dist/src/events/event.js

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from 'node:crypto';
+/** Version of the event contract below. Bumped only for incompatible changes. */
+export const EVENT_SCHEMA_VERSION = 1;
+/** A UUIDv7: time-ordered, so ids sort roughly by creation in every store. */
+export function uuidv7(now = Date.now()) {
+    const bytes = randomBytes(16);
+    const ms = BigInt(now);
+    bytes[0] = Number((ms >> 40n) & 0xffn);
+    bytes[1] = Number((ms >> 32n) & 0xffn);
+    bytes[2] = Number((ms >> 24n) & 0xffn);
+    bytes[3] = Number((ms >> 16n) & 0xffn);
+    bytes[4] = Number((ms >> 8n) & 0xffn);
+    bytes[5] = Number(ms & 0xffn);
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return format(bytes);
+}
+/**
+ * The id of the exposure of `subject` to `experiment`: a UUIDv5-style hash, identical on every
+ * send, so a destination that dedupes by id keeps one row however often the relay retries.
+ */
+export function exposureId(app, environment, experiment, subject) {
+    const bytes = createHash('sha1')
+        .update(`flags:exposure:${app}:${environment}:${experiment}:${subject}`)
+        .digest();
+    const out = Buffer.from(bytes.subarray(0, 16));
+    out[6] = (out[6] & 0x0f) | 0x50;
+    out[8] = (out[8] & 0x3f) | 0x80;
+    return format(out);
+}
+function format(bytes) {
+    const hex = Buffer.from(bytes).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** Light structural validation for events arriving over HTTP from a tenant. */
+export function parseEvents(input, app, environment) {
+    if (!Array.isArray(input))
+        throw new TypeError('events must be an array');
+    return input.map((raw, i) => {
+        const e = raw;
+        const fail = (message) => {
+            throw new TypeError(`events[${i}]: ${message}`);
+        };
+        if (typeof e.id !== 'string' || e.id.length > 64)
+            fail('id must be a string');
+        if (e.type !== 'exposure' && e.type !== 'track')
+            fail('type must be exposure or track');
+        if (typeof e.subject !== 'string' || e.subject.length === 0)
+            fail('subject is required');
+        if (typeof e.ts !== 'number' || !Number.isFinite(e.ts))
+            fail('ts must be epoch milliseconds');
+        if (e.type === 'exposure' &&
+            (typeof e.experiment !== 'string' || typeof e.variant !== 'string')) {
+            fail('an exposure needs experiment and variant');
+        }
+        if (e.type === 'track' && typeof e.name !== 'string')
+            fail('a track needs a name');
+        if (e.value !== undefined && (typeof e.value !== 'number' || !Number.isFinite(e.value))) {
+            fail('value must be a finite number');
+        }
+        return {
+            id: e.id,
+            schemaVersion: typeof e.schemaVersion === 'number' ? e.schemaVersion : EVENT_SCHEMA_VERSION,
+            // The tenant's identity and environment come from its verified token, never the payload.
+            app,
+            environment,
+            type: e.type,
+            ...(e.flag !== undefined ? { flag: String(e.flag) } : {}),
+            ...(e.experiment !== undefined ? { experiment: String(e.experiment) } : {}),
+            ...(e.variant !== undefined ? { variant: String(e.variant) } : {}),
+            ...(e.name !== undefined ? { name: String(e.name) } : {}),
+            subject: e.subject,
+            subjectType: typeof e.subjectType === 'string' ? e.subjectType : 'user',
+            ...(e.value !== undefined ? { value: e.value } : {}),
+            ...(e.props !== undefined && typeof e.props === 'object' && e.props !== null
+                ? { props: e.props }
+                : {}),
+            ts: e.ts,
+        };
+    });
+}
+//# sourceMappingURL=event.js.map

package/dist/src/events/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../../src/events/event.ts"],"names":[],"mappings":"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"}

package/dist/src/http/browser.d.ts

@@ -0,0 +1,33 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { FlagsRuntime } from '../runtime.js';
+import { BrowserTokens } from './browser_tokens.js';
+import type { ControlPlane } from './control_plane.js';
+interface RouterLike {
+    get(pattern: string, handler: (ctx: HttpContext) => unknown): {
+        as(name: string): unknown;
+    };
+    post(pattern: string, handler: (ctx: HttpContext) => unknown): {
+        as(name: string): unknown;
+    };
+    route?(pattern: string, methods: string[], handler: (ctx: HttpContext) => unknown): unknown;
+}
+/** The secret browser keys derive from: `browser.secret`, else the app key. */
+export declare function browserSecret(runtime: FlagsRuntime, appKey: unknown): string | undefined;
+/**
+ * Mounts what `browser` in `config/flags.ts` asks for: the token endpoint on every topology, and the
+ * flags API on standalone and control-plane apps.
+ */
+export declare function registerBrowser(router: RouterLike, runtime: FlagsRuntime, options: {
+    secret?: string | undefined;
+    controlPlane?: ControlPlane | undefined;
+    logger?: {
+        warn(message: string): void;
+    } | undefined;
+}): BrowserTokens | undefined;
+/**
+ * A browser token for the request's subject, e.g. to hand the first one to the frontend in a page
+ * response instead of a round-trip to the token endpoint. Needs `browser` in `config/flags.ts`.
+ */
+export declare function browserToken(ctx: HttpContext): Promise<import("./browser_tokens.js").BrowserTokenResponse>;
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/src/http/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/http/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAOlD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,UAAU,UAAU;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG;QAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5F,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG;QAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7F,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC;CAC7F;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASxF;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;CACtD,GACA,aAAa,GAAG,SAAS,CAyC3B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,+DAKlD"}

package/dist/src/http/browser.js

@@ -0,0 +1,81 @@
+import { localKeySource, remoteKeySource, } from '../topology/browser_token.js';
+import { BrowserApi } from './browser_api.js';
+import { BrowserTokens } from './browser_tokens.js';
+/** The secret browser keys derive from: `browser.secret`, else the app key. */
+export function browserSecret(runtime, appKey) {
+    if (!runtime.config.browser || runtime.config.topology === 'tenant')
+        return undefined;
+    const secret = runtime.config.browser.secret ?? releaseSecret(appKey);
+    if (!secret) {
+        throw new Error('[flags] `browser` needs a secret: set `browser.secret`, or APP_KEY in the app config');
+    }
+    return secret;
+}
+function releaseSecret(value) {
+    if (typeof value === 'string')
+        return value || undefined;
+    if (value && typeof value.release === 'function') {
+        return String(value.release()) || undefined;
+    }
+    return undefined;
+}
+/**
+ * Mounts what `browser` in `config/flags.ts` asks for: the token endpoint on every topology, and the
+ * flags API on standalone and control-plane apps.
+ */
+export function registerBrowser(router, runtime, options) {
+    const config = runtime.config;
+    const browser = config.browser;
+    if (!browser)
+        return undefined;
+    const manager = runtime.manager;
+    let keys;
+    let url;
+    if (config.topology === 'tenant') {
+        keys = remoteKeySource({
+            url: config.tenant.url,
+            token: runtime.token,
+            partition: config.tenant.partition,
+        });
+        url = browser.publicUrl ?? config.tenant.url;
+    }
+    else {
+        const secret = options.secret;
+        const prefix = (browser.prefix ??
+            (config.topology === 'control-plane' ? config.controlPlane.prefix : undefined) ??
+            '/_flags').replace(/\/$/, '');
+        keys = localKeySource(secret, manager.app, manager.environment);
+        url = browser.publicUrl ?? prefix;
+        const rulesetOf = async (environment) => {
+            if (options.controlPlane)
+                return options.controlPlane.ruleset(environment);
+            if (environment === manager.environment)
+                return runtime.source.current();
+            return runtime.store.readRuleset(environment);
+        };
+        new BrowserApi(runtime, rulesetOf, {
+            secret,
+            verifyUser: browser.verifyUser,
+            corsOrigins: browser.corsOrigins,
+        }).register(router, prefix);
+    }
+    const tokens = new BrowserTokens(runtime, keys, url, browser, options.logger);
+    if (browser.tokenRoute !== false) {
+        router
+            .get(browser.tokenRoute ?? '/_flags/token', (ctx) => tokens.handle(ctx))
+            .as('flags.browser.token');
+    }
+    return tokens;
+}
+/**
+ * A browser token for the request's subject, e.g. to hand the first one to the frontend in a page
+ * response instead of a round-trip to the token endpoint. Needs `browser` in `config/flags.ts`.
+ */
+export async function browserToken(ctx) {
+    const { getRuntime } = await import('../services/accessor.js');
+    const tokens = getRuntime().browser;
+    if (!tokens)
+        throw new Error('[flags] browserToken() needs `browser` in config/flags.ts');
+    return tokens.issue(ctx);
+}
+//# sourceMappingURL=browser.js.map

package/dist/src/http/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../src/http/browser.ts"],"names":[],"mappings":"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"}

package/dist/src/http/browser_api.d.ts

@@ -0,0 +1,48 @@
+import { type Ruleset } from '@adonis-agora/flags-core';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { FlagsRuntime } from '../runtime.js';
+import type { UserVerifier } from '../topology/verify.js';
+export interface BrowserApiOptions {
+    /** Secret the apps' signing keys derive from (see `browser_token.ts`). */
+    secret: string;
+    /** Also accept other tokens (authkit access tokens from mobile apps). */
+    verifyUser?: UserVerifier | undefined;
+    /** Origins allowed to call from browsers (CORS). */
+    corsOrigins?: string[] | undefined;
+}
+interface RouterLike {
+    get(pattern: string, handler: (ctx: HttpContext) => unknown): {
+        as(name: string): unknown;
+    };
+    post(pattern: string, handler: (ctx: HttpContext) => unknown): {
+        as(name: string): unknown;
+    };
+    route?(pattern: string, methods: string[], handler: (ctx: HttpContext) => unknown): unknown;
+}
+/**
+ * Flags for frontends that talk to the flags server directly (SPAs, mobile, static sites):
+ *
+ * - `POST <prefix>/v1/client/evaluate` — values of the flags declared `client: true`, for the
+ *   verified user. ETag over ruleset + context.
+ * - `GET  <prefix>/v1/client/stream?token=…` — server-sent `ruleset` events.
+ * - `POST <prefix>/v1/client/events` — exposures (`{ type: 'exposure', flag }`, re-evaluated here)
+ *   and tracks (`{ type: 'track', name, value?, props? }`).
+ *
+ * Tokens are minted by the apps' token endpoints (`GET /_flags/token`) or, with `verifyUser`, by
+ * an identity provider. The identity always comes from the verified token. Attributes the browser sends are merged
+ * underneath the token's, so they can never change who the user is or what the token says.
+ */
+export declare class BrowserApi {
+    #private;
+    private readonly runtime;
+    private readonly rulesetOf;
+    private readonly options;
+    constructor(runtime: FlagsRuntime, rulesetOf: (environment: string) => Promise<Ruleset>, options: BrowserApiOptions);
+    register(router: RouterLike, prefix: string): void;
+    evaluate(ctx: HttpContext): Promise<void>;
+    /** `EventSource` cannot send headers, so the token comes in the query string. Keep it short-lived. */
+    stream(ctx: HttpContext): Promise<void>;
+    events(ctx: HttpContext): Promise<void>;
+}
+export {};
+//# sourceMappingURL=browser_api.d.ts.map

package/dist/src/http/browser_api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser_api.d.ts","sourceRoot":"","sources":["../../../src/http/browser_api.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,uBAAuB,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACtC,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACpC;AAED,UAAU,UAAU;IAClB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG;QAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5F,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG;QAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7F,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC;CAC7F;AAeD;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,YACmB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACpD,OAAO,EAAE,iBAAiB,EACzC;IAEJ,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,QAU1C;IAoEK,QAAQ,CAAC,GAAG,EAAE,WAAW,iBAwB9B;IAED,sGAAsG;IAChG,MAAM,CAAC,GAAG,EAAE,WAAW,iBAgD5B;IAEK,MAAM,CAAC,GAAG,EAAE,WAAW,iBA6E5B;CACF"}