@flytedesk/app-kit 0.2.0 → 0.3.1

package/dist/flags/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Hand-written row/option types for @flytedesk/app-kit/flags.
+ *
+ * Field names here mirror prisma/fragments/flags.prisma's camelCase model fields
+ * (key/project/enabled/rollout/roles/users/updatedAt) — a consumer's generated
+ * PrismaClient, once they've run `flags-sync init` and their own `prisma generate`,
+ * satisfies FlagStore directly via `prisma.appKitFeatureFlag.findMany` /
+ * `.findUnique` / `.upsert`.
+ */
+export interface FlagRow {
+    key: string;
+    /** The row's own project column (mirrors media-planner's FeatureFlag.project
+     *  exactly). NOT what list/GET responses display as `project`, or what the
+     *  `project` list filter matches against — see FlagMeta.project below and
+     *  plugin.ts's doc comment on why. */
+    project: string;
+    enabled: boolean;
+    rollout: number;
+    /** Opaque role ids from whatever IdP/RBAC system the consumer uses — this
+     *  package has no opinion on what they mean, same as media-planner's own
+     *  FeatureFlag.roles. */
+    roles: string[];
+    /** Per-user override bag, keyed by whatever user id the consumer uses, each
+     *  value a hard on/off override that supersedes `enabled`/`rollout`/`roles` for
+     *  that one user. Evaluating overrides against a specific caller is the
+     *  consumer's own concern (same boundary media-planner draws) — this plugin only
+     *  ever reads/writes the bag as a whole, never evaluates it. */
+    users: Record<string, boolean>;
+    updatedAt: Date;
+}
+/** The fields a PATCH may write — all optional, only the ones present in the
+ *  request body (and that actually differ from the current row) are written. */
+export type FlagFields = Pick<FlagRow, "enabled" | "rollout" | "roles" | "users">;
+export type FlagPatch = Partial<FlagFields>;
+/**
+ * Flag metadata a consumer resolves from its own source of truth (media-planner's
+ * own reference implementation used a hardcoded `FLAG_ROADMAP` array) — the one
+ * genuinely app-specific piece of the reference `flags.ts` this module generalizes
+ * away via `AppKitFlagsOptions.describeFlag`. `project` here (NOT `FlagRow.project`)
+ * is what every route actually filters/sorts/displays as "the flag's project" —
+ * ported faithfully from the reference, which reads `meta.project` everywhere and
+ * never reads the DB row's own `project` column.
+ */
+export interface FlagMeta {
+    label: string;
+    description: string;
+    owner: string;
+    project: string;
+}
+/**
+ * Minimal persistence seam this plugin needs — deliberately NOT a dependency on
+ * `@prisma/client`, mirroring every other app-kit module's *Store interface (see
+ * src/profile/types.ts's ProfileStore, src/trace/types.ts's TracePrismaClient). A
+ * consumer's generated PrismaClient trivially satisfies this shape:
+ *
+ *   const store: FlagStore = {
+ *     list: () => prisma.appKitFeatureFlag.findMany(),
+ *     findByKey: (key) => prisma.appKitFeatureFlag.findUnique({ where: { key } }),
+ *     upsert: (key, patch) =>
+ *       prisma.appKitFeatureFlag.upsert({
+ *         where: { key },
+ *         create: { key, project: "unknown", ...patch },
+ *         update: patch,
+ *       }),
+ *   };
+ *
+ * A hand-rolled adapter can back it with anything else (raw SQL, a different ORM,
+ * an in-memory store for tests — see src/flags/plugin.test.ts).
+ */
+export interface FlagStore {
+    list(): Promise<FlagRow[]>;
+    /** Must return `null`, not throw/404, when no row exists for `key`. */
+    findByKey(key: string): Promise<FlagRow | null>;
+    /** Upserts the row for `key`, writing only the fields present in `patch` (fields
+     *  absent from `patch` are left unchanged on an existing row). This plugin only
+     *  ever calls this on a key it already confirmed exists via findByKey first (see
+     *  plugin.ts's PATCH handler) — the "upsert" naming matches ProfileStore's for
+     *  interface-shape consistency across app-kit's *Store seams, not because this
+     *  plugin ever creates a flag through it. */
+    upsert(key: string, patch: FlagPatch): Promise<FlagRow>;
+}
+export interface AppKitFlagsOptions {
+    /** The persistence seam — see FlagStore above. Required. */
+    store: FlagStore;
+    /**
+     * Resolves a flag key to its display metadata, or `undefined` if the key isn't
+     * known to the consumer's own catalog (e.g. media-planner's FLAG_ROADMAP). A flag
+     * with no metadata is treated as if it doesn't exist through this API at all —
+     * excluded from GET {routePrefix} (matching the reference's `.filter((x) =>
+     * x.meta)`), and 404s from GET/PATCH {routePrefix}/:key — so every route agrees
+     * on the same set of "real" flags rather than list hiding a key that :key would
+     * still happily serve. Required.
+     */
+    describeFlag: (key: string) => FlagMeta | undefined;
+    /**
+     * Fired after every successful PATCH, whether or not the patch actually changed
+     * anything (mirrors the reference's own unconditional `recordAudit` call, whose
+     * `detail` falls back to "No change" rather than skipping the call) — so a
+     * consumer replicating its own audit trail doesn't have to separately guess
+     * whether "nothing changed" is worth recording. `changes` contains only the
+     * fields that differed from the row's previous value, matching what was actually
+     * written. Not baked into a specific audit/trace mechanism (no dependency on
+     * @flytedesk/app-kit/trace or any other) — the consumer wires this to whatever
+     * they already use, same boundary `/profile` never needed to draw because it had
+     * no audit trail to begin with.
+     */
+    onChange?: (key: string, changes: FlagPatch, actor: {
+        id: string;
+        name: string;
+    }) => void | Promise<void>;
+    /** Base path the GET/PATCH routes are mounted under. Default "/flags". */
+    routePrefix?: string;
+}
+/** What GET `{routePrefix}` returns for one flag, GET `{routePrefix}/:key`, and
+ *  PATCH `{routePrefix}/:key` all share. */
+export interface FlagResponseBody {
+    key: string;
+    project: string;
+    label: string;
+    description: string;
+    enabled: boolean;
+    rollout: number;
+    roles: string[];
+    users: Record<string, boolean>;
+    owner: string;
+    /** ISO 8601. */
+    updated: string;
+}
+export interface FlagPager {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    from: number;
+    to: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+}
+/** What GET `{routePrefix}` returns — search/filter/sort/pagination/facets, same
+ *  shape as the reference `GET /flags`. */
+export interface FlagListResponseBody {
+    rows: FlagResponseBody[];
+    pager: FlagPager;
+    sort: {
+        key: string;
+        dir: "asc" | "desc";
+    };
+    filter: {
+        applied: {
+            project: string[];
+            state: string[];
+        };
+        q: string;
+        facets: {
+            project: Record<string, number>;
+            state: Record<string, number>;
+        };
+    };
+}

package/dist/flags/types.js

@@ -0,0 +1,11 @@
+/**
+ * Hand-written row/option types for @flytedesk/app-kit/flags.
+ *
+ * Field names here mirror prisma/fragments/flags.prisma's camelCase model fields
+ * (key/project/enabled/rollout/roles/users/updatedAt) — a consumer's generated
+ * PrismaClient, once they've run `flags-sync init` and their own `prisma generate`,
+ * satisfies FlagStore directly via `prisma.appKitFeatureFlag.findMany` /
+ * `.findUnique` / `.upsert`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/flags/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flytedesk/app-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Shared platform kit for flytedesk apps: flytedesk-id auth (BFF/OIDC client) and a Postgres-native trace/audit layer.",
   "type": "module",
   "license": "UNLICENSED",
@@ -29,7 +29,8 @@
   ],
   "bin": {
     "trace-sync": "./dist/cli/trace-sync.js",
-    "profile-sync": "./dist/cli/profile-sync.js"
+    "profile-sync": "./dist/cli/profile-sync.js",
+    "flags-sync": "./dist/cli/flags-sync.js"
   },
   "exports": {
     "./auth": {
@@ -47,6 +48,10 @@
     "./profile": {
       "types": "./dist/profile/index.d.ts",
       "import": "./dist/profile/index.js"
+    },
+    "./flags": {
+      "types": "./dist/flags/index.d.ts",
+      "import": "./dist/flags/index.js"
     }
   },
   "scripts": {

package/prisma/fragments/flags.meta.json

@@ -0,0 +1,4 @@
+{
+  "fragmentVersion": "1.0.0",
+  "minCliVersion": "1.0.0"
+}

package/prisma/fragments/flags.prisma

@@ -0,0 +1,52 @@
+// @flytedesk/app-kit/flags — canonical Prisma model fragment (DEC-39, ported to a
+// third fragment for the feature-flags module).
+//
+// This fragment is NOT built into a Prisma Client by this package. It is installed
+// into the *consumer's* own Prisma schema by `flags-sync init` (see
+// src/cli/flags-sync.ts, a thin wrapper around the generalized
+// src/cli/sync-engine.ts, same as trace-sync/profile-sync), and the consumer
+// generates their own client against their own schema + this fragment merged in.
+//
+// What this models: a generic project-scoped feature flag — enabled/disabled, a
+// percentage rollout, role-based targeting, and a per-user override bag. Ported
+// from media-planner's own `FeatureFlag` model (apps/api/prisma/schema.prisma) and
+// its `GET/PATCH /flags` routes (apps/api/src/routes/flags.ts), generalizing the one
+// genuinely app-specific piece: media-planner resolves flag metadata (label,
+// description, owner, project) from its own hardcoded `FLAG_ROADMAP` — this
+// fragment's row has no such columns at all, and @flytedesk/app-kit/flags's plugin
+// (see src/flags/plugin.ts) instead takes a required `describeFlag` callback so any
+// consumer can supply its own metadata source.
+//
+// Design constraints (deliberate, same reasoning as trace.prisma/profile.prisma):
+//   - No `@relation`/FK attributes anywhere. A package that ships models into a
+//     consumer's schema cannot see the consumer's own models to point a relation at.
+//   - No Prisma `enum`. Nothing here needs one today, but the same schema-global-
+//     collision reasoning applies if one ever would: it stays a plain `String`/`Int`
+//     column instead.
+//   - `String @id` on `key`: a flag's key is already a natural, stable, unique
+//     identifier (matches media-planner's own `FeatureFlag.key String @id`) — no
+//     separate surrogate key earns its keep here.
+//   - `roles String[]` and `users Json`: mirrors media-planner's own columns
+//     exactly (role ids are opaque strings from whatever IdP/RBAC system the
+//     consumer uses — this package has no opinion on what they mean; `users` is a
+//     free-form per-user override bag, `Json` because its shape is consumer-defined).
+//
+// Table name is prefixed `app_kit_` via `@@map` so it can't collide with a
+// consumer's own tables (media-planner's own table is unprefixed `FeatureFlag` —
+// this fragment intentionally does NOT reuse that name, since a consumer migrating
+// onto this fragment keeps their own table and migrates data across on their own
+// schedule, same as `/profile` did for flytedesk-id). Column names are snake_case
+// via `@map`, matching the raw SQL in
+// prisma/migrations/0003_app_kit_flags_init/migration.sql exactly.
+
+model AppKitFeatureFlag {
+  key       String   @id
+  project   String
+  enabled   Boolean  @default(true)
+  rollout   Int      @default(100)
+  roles     String[] @default([])
+  users     Json     @default("{}")
+  updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
+
+  @@map("app_kit_feature_flag")
+}

package/prisma/migrations/0003_app_kit_flags_init/migration.sql

@@ -0,0 +1,16 @@
+-- @flytedesk/app-kit/flags :: 0003_app_kit_flags_init
+--
+-- Hand-written raw SQL (this package does not run `prisma migrate dev` against its
+-- own schema — see DEC-39, and 0001_app_kit_trace_init's migration.sql for the same
+-- note). Column names, types, and defaults match prisma/fragments/flags.prisma
+-- exactly: TEXT for the String @id/String columns, BOOLEAN/INTEGER for their Prisma
+-- counterparts, TEXT[] for String[], JSONB for Json, TIMESTAMPTZ for DateTime.
+CREATE TABLE app_kit_feature_flag (
+  key        TEXT PRIMARY KEY,
+  project    TEXT NOT NULL,
+  enabled    BOOLEAN NOT NULL DEFAULT true,
+  rollout    INTEGER NOT NULL DEFAULT 100,
+  roles      TEXT[] NOT NULL DEFAULT '{}',
+  users      JSONB NOT NULL DEFAULT '{}',
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/prisma/migrations/manifest.json

@@ -12,5 +12,12 @@
     "file": "0002_app_kit_profile_init/migration.sql",
     "checksum": "sha256:62d688a2db89c77f12c61a3c98be5cfe84a6e06f8a4dda9d24b0f9acd5511b32",
     "introducedInFragmentVersion": "1.0.0"
+  },
+  {
+    "id": "0003_app_kit_flags_init",
+    "fragment": "flags",
+    "file": "0003_app_kit_flags_init/migration.sql",
+    "checksum": "sha256:55a781c3118fdaf7c4aa9405a8867cecfd8c4b9de0a6e14ef90fc364c63f7d39",
+    "introducedInFragmentVersion": "1.0.0"
   }
 ]