@adonis-agora/flags 0.0.0-stage → 0.1.0

package/dist/src/transports/transport.d.ts

@@ -0,0 +1,62 @@
+import type { FlagEvent } from '../events/event.js';
+import type { SqlClient } from '../sql.js';
+/** What a transport guarantees. The provider warns once at boot about what it does not. */
+export interface TransportCapabilities {
+    /**
+     * Can write inside the caller's database transaction, so a conversion and the business write it
+     * belongs to commit or roll back together. Only `db` can.
+     */
+    transactional: boolean;
+    /** Survives a process crash once `publish` resolved. */
+    durable: boolean;
+}
+/** A leased batch for one sink. Exactly one of `ack`/`release`/`fail` must be called. */
+export interface Delivery {
+    events: FlagEvent[];
+    /** Marks the batch delivered and moves the sink's cursor past it. */
+    ack(): Promise<void>;
+    /** Gives the lease back without moving the cursor (nothing to deliver, or shutting down). */
+    release(): Promise<void>;
+    /** Records the error and gives the lease back; the same batch is retried later. */
+    fail(error: unknown): Promise<void>;
+}
+export interface SinkStatus {
+    sink: string;
+    /** Events waiting for this sink (approximate on some transports). */
+    lag: number;
+    delivered: number;
+    leasedBy: string | null;
+    lastError: string | null;
+}
+export interface PublishOptions {
+    /** A database transaction to write in (transactional transports only). */
+    client?: SqlClient;
+}
+/**
+ * Moves events from the process that produced them to the relay that delivers them to sinks.
+ * DESIGN §8: the transport is the log, and each sink reads it at its own pace through its own
+ * cursor.
+ */
+export interface Transport {
+    readonly name: string;
+    readonly capabilities: TransportCapabilities;
+    setup?(): Promise<void>;
+    publish(events: FlagEvent[], options?: PublishOptions): Promise<void>;
+    /**
+     * Leases the next batch for `sink`. Resolves `null` when another process holds the lease, and a
+     * delivery with no events when the sink is caught up. Transports without a consumer side (`http`
+     * on a tenant) do not implement it.
+     */
+    consume?(sink: string, options: {
+        batchSize: number;
+        leaseMs: number;
+        owner: string;
+    }): Promise<Delivery | null>;
+    /** Moves a sink's cursor back to the beginning (replay / backfill a new destination). */
+    rewind?(sink: string): Promise<void>;
+    status?(sinks: string[]): Promise<SinkStatus[]>;
+    /** The newest id every listed sink has delivered (what is safe to prune). */
+    safePruneId?(sinks: string[]): Promise<number>;
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/src/transports/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/transports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,qEAAqE;IACrE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,6FAA6F;IAC7F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,mFAAmF;IACnF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE;;;;OAIG;IACH,OAAO,CAAC,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC7D,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC5B,yFAAyF;IACzF,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAChD,6EAA6E;IAC7E,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/src/transports/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/src/transports/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/transports/transport.ts"],"names":[],"mappings":""}

package/dist/src/types.d.ts

@@ -0,0 +1,30 @@
+import type { JsonValue } from '@adonis-agora/flags-core';
+/**
+ * The typed flag registry. Flags declared in `config/flags.ts` are added with
+ * `interface FlagsList extends InferFlags<typeof flagsConfig> {}`, and flags created in the console
+ * with `node ace flags:types` (it writes a `.d.ts` that augments this interface).
+ */
+export interface FlagsList {
+}
+/**
+ * Type-level settings. `node ace flags:types` sets `strictKeys: true`: once every flag (code and
+ * console) is in {@link FlagsList}, an unknown key is a compile error. Without it, any string is
+ * accepted (flags created in the console since the last generation still compile) and declared
+ * keys are offered by autocomplete.
+ */
+export interface FlagsSettings {
+}
+type Declared = Extract<keyof FlagsList, string>;
+type Strict = FlagsSettings extends {
+    strictKeys: true;
+} ? true : false;
+/** Flag keys: the declared ones, plus any string unless `strictKeys` is on. */
+export type FlagKey = keyof FlagsList extends never ? string : Strict extends true ? Declared : Declared | (string & {});
+/** The value type of a flag key (any JSON for keys not in {@link FlagsList}). */
+export type FlagValue<K extends string> = K extends keyof FlagsList ? FlagsList[K] : JsonValue;
+/** Keys whose value is boolean (what `enabled()` accepts). */
+export type BooleanFlagKey = keyof FlagsList extends never ? string : ({
+    [K in keyof FlagsList]: FlagsList[K] extends boolean ? K : never;
+}[keyof FlagsList] & string) | (Strict extends true ? never : string & {});
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,SAAS;CAAG;AAE7B;;;;;GAKG;AACH,MAAM,WAAW,aAAa;CAAG;AAEjC,KAAK,QAAQ,GAAG,OAAO,CAAC,MAAM,SAAS,EAAE,MAAM,CAAC,CAAC;AACjD,KAAK,MAAM,GAAG,aAAa,SAAS;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AAExE,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,MAAM,SAAS,SAAS,KAAK,GAC/C,MAAM,GACN,MAAM,SAAS,IAAI,GACjB,QAAQ,GACR,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/B,iFAAiF;AACjF,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,MAAM,SAAS,SAAS,KAAK,GACtD,MAAM,GAEF,CAAC;KAAG,CAAC,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,SAAS,CAAC,GACpF,MAAM,CAAC,GACT,CAAC,MAAM,SAAS,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/usage.d.ts

@@ -0,0 +1,18 @@
+import type { UsageRow } from './stores/store.js';
+/**
+ * Counts evaluations per flag in memory and hands them off periodically — the input of stale-flag
+ * detection ("not evaluated in 30 days"). Counting is a Map increment; nothing touches I/O on the
+ * evaluation path.
+ */
+export declare class UsageCounter {
+    #private;
+    private readonly environment;
+    private readonly sink;
+    private readonly onError?;
+    constructor(environment: string, sink: (rows: UsageRow[]) => Promise<void>, onError?: ((error: unknown) => void) | undefined);
+    hit(flag: string): void;
+    start(intervalMs?: number): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/src/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;GAIG;AACH,qBAAa,YAAY;;IAKrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAH3B,YACmB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,EACzC,OAAO,CAAC,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,aAAA,EACjD;IAEJ,GAAG,CAAC,IAAI,EAAE,MAAM,QAEf;IAED,KAAK,CAAC,UAAU,SAAS,QAGxB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3B;CACF"}

package/dist/src/usage.js

@@ -0,0 +1,52 @@
+/**
+ * Counts evaluations per flag in memory and hands them off periodically — the input of stale-flag
+ * detection ("not evaluated in 30 days"). Counting is a Map increment; nothing touches I/O on the
+ * evaluation path.
+ */
+export class UsageCounter {
+    environment;
+    sink;
+    onError;
+    #counts = new Map();
+    #timer;
+    constructor(environment, sink, onError) {
+        this.environment = environment;
+        this.sink = sink;
+        this.onError = onError;
+    }
+    hit(flag) {
+        this.#counts.set(flag, (this.#counts.get(flag) ?? 0) + 1);
+    }
+    start(intervalMs = 60_000) {
+        this.#timer ??= setInterval(() => void this.flush(), intervalMs);
+        this.#timer.unref();
+    }
+    async flush() {
+        if (this.#counts.size === 0)
+            return;
+        const day = new Date().toISOString().slice(0, 10);
+        const rows = [...this.#counts].map(([flag, evaluations]) => ({
+            environment: this.environment,
+            flag,
+            day,
+            evaluations,
+        }));
+        this.#counts.clear();
+        try {
+            await this.sink(rows);
+        }
+        catch (error) {
+            // Put the counts back; they go out with the next flush.
+            for (const row of rows)
+                this.#counts.set(row.flag, (this.#counts.get(row.flag) ?? 0) + row.evaluations);
+            this.onError?.(error);
+        }
+    }
+    async close() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = undefined;
+        await this.flush();
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/src/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/usage.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,YAAY;IAKJ,WAAW;IACX,IAAI;IACJ,OAAO;IAN1B,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpC,MAAM,CAA6B;IAEnC,YACmB,WAAmB,EACnB,IAAyC,EACzC,OAAkC;2BAFlC,WAAW;oBACX,IAAI;uBACJ,OAAO;IACvB,CAAC;IAEJ,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,UAAU,GAAG,MAAM;QACvB,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACpC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3D,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,IAAI;YACJ,GAAG;YACH,WAAW;SACZ,CAAC,CAAC,CAAC;QACJ,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,wDAAwD;YACxD,KAAK,MAAM,GAAG,IAAI,IAAI;gBACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;YAClF,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,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/stubs/config/flags.stub

@@ -0,0 +1,50 @@
+{{{
+  exports({ to: app.configPath('flags.ts') })
+}}}
+import env from '#start/env'
+import app from '@adonisjs/core/services/app'
+import { defineConfig, flag, type InferFlags } from '@adonis-agora/flags'
+
+const flagsConfig = defineConfig({
+  /**
+   * Flags declared in code: their type and the value served when the ruleset cannot answer.
+   * Targeting (who gets what) is edited in the console or with \`node ace flags:set\`.
+   */
+  flags: {
+    example_flag: flag.boolean({
+      default: false,
+      description: 'What this flag controls',
+      owner: 'your-team',
+      // Shown by \`node ace flags:stale\` once this date passes.
+      expiresAt: '2027-06-30',
+      // Allowed to reach the browser through ctx.flags.all() / useFlag().
+      client: true,
+    }),
+  },
+
+  /**
+   * Which environment's ruleset this process reads (and the console and \`flags:*\` commands edit
+   * by default). Each environment has its own targeting.
+   */
+  environment: env.get('FLAGS_ENVIRONMENT', app.inProduction ? 'production' : 'development'),
+
+  /**
+   * Metrics experiments are judged by, computed from \`flags.track(subject, 'event', { value })\`.
+   * Build them with \`metric\` from '@adonis-agora/flags'.
+   */
+  metrics: {
+    // conversion: metric.conversion('purchase'),
+    // revenue: metric.sum('purchase', { cupedMs: 14 * 24 * 3600 * 1000 }),
+  },
+
+  /** Experiment key (the flag key) → the metrics that decide it and the ones that must not regress. */
+  experiments: {
+    // checkout_v2: { metrics: ['conversion', 'revenue'], guardrails: [] },
+  },
+})
+
+export default flagsConfig
+
+declare module '@adonis-agora/flags/types' {
+  interface FlagsList extends InferFlags<typeof flagsConfig> {}
+}

package/dist/stubs/config/flags_dashboard.stub

@@ -0,0 +1,35 @@
+{{{
+  exports({ to: app.configPath('flags_dashboard.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/flags/dashboard'
+
+/**
+ * Configuration for the @adonis-agora/flags console.
+ *
+ * Without \`authorize\` the console is open OUTSIDE production and answers
+ * every request with 403 in production (a warning is logged at boot). Set
+ * \`authorize\` to choose who may open it: an inline function,
+ * an authorizer class (\`@inject()\` works), or a lazy import of one
+ * (\`() => import('#policies/console_access')\`). It answers \`true\`/\`false\`,
+ * \`{ allowed, reason?: 'unauthenticated' | 'forbidden' }\` or \`{ redirectTo }\`:
+ * \`unauthenticated\` is a 401, any other denial (or a throw) a 403. With authkit,
+ * \`authkitDashboardAuthorize(...)\` from @adonis-agora/authkit-client fits as-is.
+ * For machine access use \`authorizeByToken({ token: env.get('CONSOLE_TOKEN') })\`.
+ *
+ * An identity provider in config/flags.ts (\`identity: identities.adonisAuth({ canOpenConsole })\`,
+ * \`identities.authkit()\` or your own class) answers both questions for you.
+ *
+ * \`actor\` names who made a change (audit log, two-person approvals). Default:
+ * the signed-in user's id, else 'dashboard'.
+ *
+ * Set \`enabled: false\` to remove it entirely — no routes are registered at all.
+ */
+export default defineConfig({
+  // enabled: true,
+  // path: '/flags',
+  // authorize: async (ctx) => {
+  //   if (!(await ctx.auth.check())) return { redirectTo: '/login' }
+  //   return ctx.auth.user?.isAdmin === true
+  // },
+  // actor: (ctx) => ctx.auth.user ? { id: String(ctx.auth.user.id), name: ctx.auth.user.email } : undefined,
+})

package/dist/stubs/database/migrations/create_flags_tables.stub

@@ -0,0 +1,27 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_flags_tables.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+import { createFlagsTables, dropFlagsTables } from '@adonis-agora/flags'
+
+/**
+ * The flags tables, for apps that run DDL explicitly.
+ *
+ * **You may not need this file.** \`@adonis-agora/flags\` creates its tables at boot
+ * (\`autoCreateSchema\`, on by default), like the other Agora libraries. Keep this migration if you
+ * want migrations to own the schema, and set \`autoCreateSchema: false\` in config/flags.ts. Both
+ * paths call the same \`createFlagsTables\`.
+ */
+export default class extends BaseSchema {
+  async up() {
+    this.defer(async (db) => {
+      await createFlagsTables(db as never, { partitionEvents: false })
+    })
+  }
+
+  async down() {
+    this.defer(async (db) => {
+      await dropFlagsTables(db as never)
+    })
+  }
+}

package/dist/stubs/main.d.ts

@@ -0,0 +1,3 @@
+/** Absolute path to the published stubs directory (`dist/stubs/`), computed lazily. */
+export declare function stubsRoot(): string;
+//# sourceMappingURL=main.d.ts.map

package/dist/stubs/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAIA,uFAAuF;AACvF,wBAAgB,SAAS,IAAI,MAAM,CAGlC"}

package/dist/stubs/main.js

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url';
+let cached;
+/** Absolute path to the published stubs directory (`dist/stubs/`), computed lazily. */
+export function stubsRoot() {
+    if (cached === undefined)
+        cached = fileURLToPath(new URL('./', import.meta.url));
+    return cached;
+}
+//# sourceMappingURL=main.js.map

package/dist/stubs/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAA0B,CAAC;AAE/B,uFAAuF;AACvF,MAAM,UAAU,SAAS;IACvB,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,181 @@
 {
   "name": "@adonis-agora/flags",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Feature flags, A/B experiments and their analysis for AdonisJS — typed flags in code, targeting in your database, exposures relayed to Postgres, Parquet/DuckDB, ClickHouse or PostHog. Speaks OpenFeature. Part of the Agora ecosystem.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-agora-flags.git",
+    "directory": "packages/adonis"
+  },
+  "homepage": "https://davidecarvalho.github.io/agora/docs/flags",
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/adonis-agora-flags/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "feature-flags",
+    "ab-testing",
+    "experiments",
+    "openfeature",
+    "ofrep",
+    "agora",
+    "tanstack-intent"
+  ],
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./types": {
+      "types": "./dist/src/types.d.ts",
+      "import": "./dist/src/types.js",
+      "default": "./dist/src/types.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js",
+      "default": "./dist/services/main.js"
+    },
+    "./flags_provider": {
+      "types": "./dist/providers/flags_provider.d.ts",
+      "import": "./dist/providers/flags_provider.js",
+      "default": "./dist/providers/flags_provider.js"
+    },
+    "./flags_middleware": {
+      "types": "./dist/src/http/flags_middleware.d.ts",
+      "import": "./dist/src/http/flags_middleware.js",
+      "default": "./dist/src/http/flags_middleware.js"
+    },
+    "./flag_middleware": {
+      "types": "./dist/src/http/flag_middleware.d.ts",
+      "import": "./dist/src/http/flag_middleware.js",
+      "default": "./dist/src/http/flag_middleware.js"
+    },
+    "./openfeature": {
+      "types": "./dist/src/openfeature/provider.d.ts",
+      "import": "./dist/src/openfeature/provider.js",
+      "default": "./dist/src/openfeature/provider.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing/index.d.ts",
+      "import": "./dist/src/testing/index.js",
+      "default": "./dist/src/testing/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/main.d.ts",
+      "import": "./dist/commands/main.js",
+      "default": "./dist/commands/main.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js",
+      "default": "./dist/configure.js"
+    },
+    "./dashboard": {
+      "types": "./dist/src/dashboard/index.d.ts",
+      "import": "./dist/src/dashboard/index.js",
+      "default": "./dist/src/dashboard/index.js"
+    },
+    "./dashboard_provider": {
+      "types": "./dist/providers/dashboard_provider.d.ts",
+      "import": "./dist/providers/dashboard_provider.js",
+      "default": "./dist/providers/dashboard_provider.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "dependencies": {
+    "@adonis-agora/flags-core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@adonis-agora/authkit-client": ">=0.18.0 <2.0.0 || >=1.0.0-rc.0 <2.0.0",
+    "@adonis-agora/durable": ">=0.40.0 <2.0.0 || >=1.0.0-rc.0 <2.0.0",
+    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/lucid": "^22.4.0",
+    "@adonisjs/redis": "^10.0.0 || ^11.0.0",
+    "@adonisjs/transmit": "^3.0.0",
+    "@duckdb/node-api": ">=1.4.0-r.0",
+    "@openfeature/server-sdk": "^1.17.0",
+    "@opentelemetry/api": "^1.9.0",
+    "edge.js": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonis-agora/authkit-client": {
+      "optional": true
+    },
+    "@adonis-agora/durable": {
+      "optional": true
+    },
+    "@adonisjs/lucid": {
+      "optional": true
+    },
+    "@adonisjs/redis": {
+      "optional": true
+    },
+    "@adonisjs/transmit": {
+      "optional": true
+    },
+    "@duckdb/node-api": {
+      "optional": true
+    },
+    "@openfeature/server-sdk": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "edge.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonis-agora/authkit-client": "1.0.0-rc.0",
+    "@adonis-agora/durable": "1.0.0-rc.11",
+    "@adonis-agora/flags-dashboard": "0.1.0",
+    "@adonisjs/assembler": "8.6.0",
+    "@adonisjs/core": "7.6.0",
+    "@adonisjs/lucid": "22.4.2",
+    "@duckdb/node-api": "1.5.6-r.2",
+    "@openfeature/core": "1.12.0",
+    "@openfeature/server-sdk": "1.23.0",
+    "@opentelemetry/api": "1.9.0",
+    "@tanstack/intent": "0.5.6",
+    "@testcontainers/postgresql": "12.2.1",
+    "@testcontainers/redis": "12.2.1",
+    "@types/luxon": "3.7.6",
+    "@types/node": "26.6.6",
+    "@types/pg": "8.23.1",
+    "better-sqlite3": "13.0.3",
+    "edge.js": "6.5.1",
+    "ioredis": "5.11.1",
+    "jose": "6.2.15",
+    "luxon": "3.7.2",
+    "mysql2": "3.24.6",
+    "pg": "8.23.1",
+    "typescript": "7.0.2",
+    "vitest": "5.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && pnpm run copy:stubs && pnpm run copy:spa",
+    "copy:stubs": "rm -rf dist/stubs/config dist/stubs/database && mkdir -p dist/stubs && cp -r stubs/config stubs/database dist/stubs/",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run -c vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "copy:spa": "mkdir -p dist/assets && rm -rf dist/assets/spa && cp -r ../dashboard/dist/spa dist/assets/spa"
+  }
 }

package/skills/flags-basics/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: flags-basics
+description: >-
+  Set up @adonis-agora/flags in an AdonisJS 7 app and read feature flags: node
+  ace configure, declaring typed flags in config/flags.ts with flag.boolean /
+  flag.string({ variants }) / flag.number / flag.json, the FlagsList module
+  augmentation with InferFlags, ctx.flags.enabled / value / variant / details,
+  the flags service (flags.for(user)), the `flag` route-guard middleware, the
+  Edge @flag tag, client: true flags for the browser, flags:set (on, off,
+  kill, 25%, variant), and fakeFlags / createTestFlags for tests. Use for
+  "add a feature flag", "roll out to 10% of users", "hide a route behind a
+  flag", "flag is always the default", or "test code that reads a flag".
+metadata:
+  type: core
+  library: "@adonis-agora/flags"
+  library_version: "0.1.0"
+  framework: adonisjs
+license: MIT
+sources:
+  - 'DavideCarvalho/adonis-agora-flags:docs/getting-started.mdx'
+  - 'DavideCarvalho/adonis-agora-flags:docs/declaring-flags.mdx'
+  - 'DavideCarvalho/adonis-agora-flags:docs/reading-flags.mdx'
+  - 'DavideCarvalho/adonis-agora-flags:docs/targeting.mdx'
+  - 'DavideCarvalho/adonis-agora-flags:docs/testing.mdx'
+---
+
+# @adonis-agora/flags — declaring and reading flags
+
+Flags are declared in code (key, type, default); who gets what lives in the
+database and changes without a deploy. Evaluation is in memory: reading a flag
+never waits on I/O and never throws — on any problem the declared default is
+served.
+
+## Setup
+
+```sh
+node ace add @adonis-agora/flags
+```
+
+```ts
+// config/flags.ts
+import { defineConfig, flag, type InferFlags } from '@adonis-agora/flags'
+
+const flagsConfig = defineConfig({
+  flags: {
+    new_player: flag.boolean({ default: false, owner: 'video-team', expiresAt: '2027-03-31' }),
+    checkout: flag.string({ default: 'control', variants: ['control', 'one_page'] }),
+    max_uploads: flag.number({ default: 10 }),
+  },
+})
+export default flagsConfig
+
+declare module '@adonis-agora/flags/types' {
+  interface FlagsList extends InferFlags<typeof flagsConfig> {}
+}
+```
+
+Flags are usually created in the console (`/flags` → New flag: key, type, default, variants,
+owner); their declaration travels with the ruleset. `node ace flags:types` writes
+`types/flags.d.ts` so console flags are typed (and turns on strict keys). Declaring in
+`config/flags.ts`, as above, is the alternative; code wins when both exist.
+
+## Core patterns
+
+### Pattern 1 — read a flag in a controller
+
+```ts no-check
+async show({ flags, inertia }: HttpContext) {
+  if (await flags.enabled('new_player')) return inertia.render('player/new')
+  return inertia.render('player/classic')
+}
+```
+
+`ctx.flags` evaluates for the authkit identity when `@adonis-agora/authkit-client`
+is installed (targetingKey = `sub`; attributes `email`, `emailDomain`,
+`globalRoles`, `orgId`, `orgSlug`, `orgRole`), else `ctx.auth.user`.
+`identity` in the config replaces all of it with one `FlagsIdentityProvider`
+(`subject`, `actor`, `authorizeConsole`, `can`): `identities.authkit()`,
+`identities.adonisAuth({ guard, canOpenConsole: (user, ctx) =>
+ctx.bouncer.allows(manageFlags) })`, or a class implementing the interface.
+Outside HTTP:
+
+```ts
+import flags from '@adonis-agora/flags/services/main'
+await flags.for(user).value('max_uploads')
+```
+
+### Pattern 2 — targeting attributes from server state
+
+```ts no-check
+// config/flags.ts
+attributes: async (subject) => {
+  const user = await User.find(subject.id)
+  return { plan: user?.plan, orgId: user?.organizationId }
+},
+```
+
+### Pattern 3 — guard a route
+
+```ts
+router.get('/beta', [BetaController]).use(middleware.flag({ flag: 'new_player' }))
+```
+
+Answers 404 when the flag says no.
+
+### Pattern 4 — change a flag
+
+```sh
+node ace flags:set new_player 10%   # rollout; raising it only adds people
+node ace flags:set new_player on
+node ace flags:set new_player kill  # kill switch: off for everyone
+```
+
+### Pattern 5 — tests
+
+```ts
+import { fakeFlags } from '@adonis-agora/flags/testing'
+test('new player', async ({ client, cleanup }) => {
+  cleanup(fakeFlags({ new_player: true }))
+})
+```
+
+## Common mistakes
+
+### HIGH — Expecting `setEnabled(true)` / `unkill` to turn a boolean flag on
+
+`enabled` is the kill switch. Turning targeting back on does not serve `on`.
+Use `flags:set <flag> on` (`admin.turnOn`).
+
+### HIGH — Sending flags to the browser with `ctx.flags.all()` and getting `{}`
+
+Only flags declared with `client: true` are included, so internal names never
+leak. Declare the flag with `client: true`.
+
+### MEDIUM — Reading targeting attributes from the request
+
+`attributes` must come from server state. A query string or header lets users
+pick their own variant.
+
+### MEDIUM — Forgetting the `declare module` block
+
+Without it keys are plain strings: typos compile and values are untyped.