@digimuza/saas-core 0.0.2

package/dist/features/bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.js","sourceRoot":"","sources":["../../src/features/bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,SAAiB;IACrD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAE3E;;;;OAIG;IACH,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,UAAkB,EAClB,SAA6B;IAE7B,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,UAAU,CAAC;AAC/C,CAAC"}

package/dist/features/index.d.ts

@@ -0,0 +1,15 @@
+import type { FeatureFlagMap, FeatureFlagRegistry } from "./registry.ts";
+import { type FeaturesService } from "./service.ts";
+export { bucketOf, isInRollout } from "./bucket.ts";
+export { defineFeatureFlags, mergeFeatureFlags, type FeatureFlagDefinition, type FeatureFlagKey, type FeatureFlagMap, type FeatureFlagRegistry, type FeatureFlagVariant, } from "./registry.ts";
+export { createFeaturesService, type FeaturesService, type FeaturesServiceDeps, type FlagSubject, type ResolvedFlag, type SetFlagInput, type UnsetFlagInput, } from "./service.ts";
+export { FLAG_SCOPE_PRECEDENCE, type FeatureFlagScope } from "../db/schema/features.ts";
+/**
+ * Build a service from configuration, using `APP_NAME` as the application scope.
+ *
+ * There is no default `features` export: flags are application-defined, so a
+ * service with an empty registry could not answer anything. Construct your own
+ * with your registry.
+ */
+export declare function createConfiguredFeaturesService<T extends FeatureFlagMap>(registry: FeatureFlagRegistry<T>): FeaturesService<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/features/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/features/index.ts"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,SAAS,cAAc,EACtE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,eAAe,CAAC,CAAC,CAAC,CAepB"}

package/dist/features/index.js

@@ -0,0 +1,78 @@
+/**
+ * Public feature flags surface: `@digimuza/saas-core/feature-flags`. Server-only.
+ *
+ * Simple flags with four scopes, resolved most-specific-first:
+ *
+ * ```
+ * global  <  application  <  workspace  <  user
+ * ```
+ *
+ * Deliberately **not** a feature management platform. No segments, no rule
+ * engines, no audience builders — a flag is on or off, optionally for a
+ * percentage, optionally with a variant. Anything more belongs in a product that
+ * does only that.
+ *
+ * ## Declare flags in code
+ *
+ * ```ts
+ * import { defineFeatureFlags, createFeaturesService } from "@digimuza/saas-core/feature-flags";
+ * import { getDatabase } from "@digimuza/saas-core/db";
+ *
+ * export const flags = defineFeatureFlags({
+ *   "new-editor": { default: false, description: "Rebuilt document editor" },
+ *   "ranking": { default: true, variants: ["control", "v2"], defaultVariant: "control" },
+ * });
+ *
+ * export const features = createFeaturesService({
+ *   db: getDatabase(),
+ *   registry: flags,
+ *   application: "docs-app",
+ * });
+ * ```
+ *
+ * Definitions live in code so that a fresh database behaves the same as a
+ * configured one, a typo is a compile error, and deleting a flag from the code
+ * deletes it from the product. Database rows are only *overrides*.
+ *
+ * ## Read them
+ *
+ * ```ts
+ * const subject = { workspaceId: context.workspaceId, userId: user.id };
+ *
+ * if (await features.isEnabled("new-editor", subject)) { ... }
+ *
+ * // Better: one query per request, then pass it to the client.
+ * const resolved = await features.all(subject);
+ * ```
+ */
+import { config } from "../config/index.js";
+import { getDatabase } from "../db/client.js";
+import { createFeaturesService } from "./service.js";
+export { bucketOf, isInRollout } from "./bucket.js";
+export { defineFeatureFlags, mergeFeatureFlags, } from "./registry.js";
+export { createFeaturesService, } from "./service.js";
+export { FLAG_SCOPE_PRECEDENCE } from "../db/schema/features.js";
+/**
+ * Build a service from configuration, using `APP_NAME` as the application scope.
+ *
+ * There is no default `features` export: flags are application-defined, so a
+ * service with an empty registry could not answer anything. Construct your own
+ * with your registry.
+ */
+export function createConfiguredFeaturesService(registry) {
+    return createFeaturesService({
+        /**
+         * Both dependencies are getters, so the `app` and `database` configuration
+         * sections resolve on first use rather than at import — constructing the
+         * service never requires configuration to be present.
+         */
+        get db() {
+            return getDatabase();
+        },
+        registry,
+        get application() {
+            return config.app.name;
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/features/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/features/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,qBAAqB,EAAwB,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,GAMlB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,GAOtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAyB,MAAM,0BAA0B,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAAgC;IAEhC,OAAO,qBAAqB,CAAC;QAC3B;;;;WAIG;QACH,IAAI,EAAE;YACJ,OAAO,WAAW,EAAE,CAAC;QACvB,CAAC;QACD,QAAQ;QACR,IAAI,WAAW;YACb,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACzB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/features/registry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A flag, declared in code.
+ *
+ * The definition lives here rather than in the database so that a fresh database
+ * behaves the same as a configured one, a typo in a key is a compile error, and
+ * deleting the flag from the code deletes it from the product. Database rows are
+ * only *overrides* — deviations from these defaults.
+ */
+export interface FeatureFlagDefinition {
+    /** Value when no override matches. */
+    readonly default: boolean;
+    readonly description?: string;
+    /**
+     * Permitted variant values.
+     *
+     * Declaring them makes `set` reject a typo at write time — the alternative is
+     * discovering it when a variant silently matches nothing in a switch.
+     */
+    readonly variants?: readonly string[];
+    /** Variant when no override supplies one. */
+    readonly defaultVariant?: string;
+}
+export type FeatureFlagMap = Record<string, FeatureFlagDefinition>;
+export interface FeatureFlagRegistry<T extends FeatureFlagMap = FeatureFlagMap> {
+    readonly flags: T;
+}
+/**
+ * Declare an application's flags.
+ *
+ * ```ts
+ * export const appFlags = defineFeatureFlags({
+ *   "new-editor": { default: false, description: "Rebuilt document editor" },
+ *   "ranking": { default: true, variants: ["control", "v2"], defaultVariant: "control" },
+ * });
+ * ```
+ *
+ * The `const` type parameter preserves the literal keys, which is what makes
+ * `isEnabled("new-editor")` autocomplete and a misspelling fail to compile.
+ */
+export declare function defineFeatureFlags<const T extends FeatureFlagMap>(flags: T): FeatureFlagRegistry<T>;
+/**
+ * Combine registries. Duplicate keys throw.
+ *
+ * Two modules each defining `"new-editor"` with different defaults would make the
+ * flag's behaviour depend on import order.
+ */
+export declare function mergeFeatureFlags<A extends FeatureFlagMap, B extends FeatureFlagMap>(first: FeatureFlagRegistry<A>, second: FeatureFlagRegistry<B>): FeatureFlagRegistry<A & B>;
+export type FeatureFlagKey<T extends FeatureFlagMap> = keyof T & string;
+/** The variant type for one flag: its declared union, or `string`. */
+export type FeatureFlagVariant<T extends FeatureFlagMap, K extends FeatureFlagKey<T>> = T[K]["variants"] extends readonly (infer V)[] ? V : string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/features/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/features/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAEnE,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IAC5E,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAC/D,KAAK,EAAE,CAAC,GACP,mBAAmB,CAAC,CAAC,CAAC,CAgCxB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAClF,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAC7B,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC7B,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAQ5B;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,cAAc,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC;AAExE,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,CAC5B,CAAC,SAAS,cAAc,EACxB,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,IACzB,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC"}

package/dist/features/registry.js

@@ -0,0 +1,52 @@
+import { InvalidInputError } from "../errors.js";
+/**
+ * Declare an application's flags.
+ *
+ * ```ts
+ * export const appFlags = defineFeatureFlags({
+ *   "new-editor": { default: false, description: "Rebuilt document editor" },
+ *   "ranking": { default: true, variants: ["control", "v2"], defaultVariant: "control" },
+ * });
+ * ```
+ *
+ * The `const` type parameter preserves the literal keys, which is what makes
+ * `isEnabled("new-editor")` autocomplete and a misspelling fail to compile.
+ */
+export function defineFeatureFlags(flags) {
+    for (const [key, definition] of Object.entries(flags)) {
+        if (!/^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$/.test(key)) {
+            /**
+             * Keys reach URLs, log lines and client payloads. Constraining them here
+             * avoids having to escape them everywhere downstream.
+             */
+            throw new InvalidInputError(`"${key}" is not a valid flag key: use lowercase alphanumerics, dots, dashes or underscores.`);
+        }
+        if (definition.variants !== undefined) {
+            if (definition.variants.length === 0) {
+                throw new InvalidInputError(`Flag "${key}" declares an empty variant list.`);
+            }
+            if (definition.defaultVariant !== undefined &&
+                !definition.variants.includes(definition.defaultVariant)) {
+                throw new InvalidInputError(`Flag "${key}" has a defaultVariant that is not among its variants.`);
+            }
+        }
+        else if (definition.defaultVariant !== undefined) {
+            throw new InvalidInputError(`Flag "${key}" declares a defaultVariant without declaring variants.`);
+        }
+    }
+    return { flags };
+}
+/**
+ * Combine registries. Duplicate keys throw.
+ *
+ * Two modules each defining `"new-editor"` with different defaults would make the
+ * flag's behaviour depend on import order.
+ */
+export function mergeFeatureFlags(first, second) {
+    const collisions = Object.keys(second.flags).filter((key) => key in first.flags);
+    if (collisions.length > 0) {
+        throw new InvalidInputError(`Feature flags already defined: ${collisions.join(", ")}.`);
+    }
+    return { flags: { ...first.flags, ...second.flags } };
+}
+//# sourceMappingURL=registry.js.map

package/dist/features/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/features/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA+BjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAQ;IAER,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,qCAAqC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD;;;eAGG;YACH,MAAM,IAAI,iBAAiB,CACzB,IAAI,GAAG,sFAAsF,CAC9F,CAAC;QACJ,CAAC;QAED,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACtC,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,iBAAiB,CAAC,SAAS,GAAG,mCAAmC,CAAC,CAAC;YAC/E,CAAC;YACD,IACE,UAAU,CAAC,cAAc,KAAK,SAAS;gBACvC,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,EACxD,CAAC;gBACD,MAAM,IAAI,iBAAiB,CACzB,SAAS,GAAG,wDAAwD,CACrE,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,IAAI,UAAU,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACnD,MAAM,IAAI,iBAAiB,CACzB,SAAS,GAAG,yDAAyD,CACtE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA6B,EAC7B,MAA8B;IAE9B,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IAEjF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;AACxD,CAAC"}

package/dist/features/service.d.ts

@@ -0,0 +1,78 @@
+import type { FeatureFlagRow, FeatureFlagScope } from "../db/schema/index.ts";
+import type { CoreDatabase } from "../db/types.ts";
+import type { FeatureFlagKey, FeatureFlagMap, FeatureFlagRegistry, FeatureFlagVariant } from "./registry.ts";
+/**
+ * Who a flag is being evaluated for.
+ *
+ * Plain ids, deliberately, rather than a `WorkspaceContext`. Flags are read many
+ * times per request — every conditional render — and a membership check per read
+ * would make them expensive enough that people would cache them badly. A flag
+ * state is configuration, not tenant data.
+ *
+ * Pass ids that came from a verified context. The service will not check for you.
+ */
+export interface FlagSubject {
+    readonly workspaceId?: string;
+    readonly userId?: string;
+}
+/** A resolved flag, with enough detail to explain itself. */
+export interface ResolvedFlag {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly variant: string | undefined;
+    /** Which scope decided it. `"default"` means no override matched. */
+    readonly source: FeatureFlagScope | "default";
+}
+export interface SetFlagInput {
+    readonly key: string;
+    readonly scope: FeatureFlagScope;
+    /** Required for `scope: "application"`. */
+    readonly application?: string;
+    /** Required for `scope: "workspace"`. */
+    readonly workspaceId?: string;
+    /** Required for `scope: "user"`. */
+    readonly userId?: string;
+    readonly enabled: boolean;
+    readonly variant?: string | null;
+    /** 0-100. Null or omitted means everyone the override applies to. */
+    readonly rolloutPercentage?: number | null;
+    readonly description?: string;
+}
+export type UnsetFlagInput = Pick<SetFlagInput, "key" | "scope" | "application" | "workspaceId" | "userId">;
+export interface FeaturesService<T extends FeatureFlagMap> {
+    /** Whether a flag is on for this subject. */
+    isEnabled(key: FeatureFlagKey<T>, subject?: FlagSubject): Promise<boolean>;
+    /**
+     * The active variant, or `undefined`.
+     *
+     * A disabled flag has no variant: returning one would invite code that reads
+     * the variant without checking `isEnabled` first.
+     */
+    getVariant<K extends FeatureFlagKey<T>>(key: K, subject?: FlagSubject): Promise<FeatureFlagVariant<T, K> | undefined>;
+    /** One flag, with the scope that decided it. For a debug view. */
+    resolve(key: FeatureFlagKey<T>, subject?: FlagSubject): Promise<ResolvedFlag>;
+    /**
+     * Every flag, resolved in **one** query.
+     *
+     * The recommended path: resolve once per request and pass the result to the
+     * client, rather than querying per conditional.
+     */
+    all(subject?: FlagSubject): Promise<Map<FeatureFlagKey<T>, ResolvedFlag>>;
+    /** Create or replace an override. Idempotent. */
+    set(input: SetFlagInput): Promise<FeatureFlagRow>;
+    /** Remove an override, falling back to the next-broadest scope. */
+    unset(input: UnsetFlagInput): Promise<void>;
+    /** Every stored override for a key, broadest first. */
+    overrides(key: FeatureFlagKey<T>): Promise<FeatureFlagRow[]>;
+}
+export interface FeaturesServiceDeps<T extends FeatureFlagMap> {
+    readonly db: CoreDatabase;
+    readonly registry: FeatureFlagRegistry<T>;
+    /**
+     * Which application this process is. Required for `application`-scoped
+     * overrides to match — without it they are ignored rather than guessed at.
+     */
+    readonly application?: string;
+}
+export declare function createFeaturesService<T extends FeatureFlagMap>(deps: FeaturesServiceDeps<T>): FeaturesService<T>;
+//# sourceMappingURL=service.d.ts.map

package/dist/features/service.d.ts.map

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

package/dist/features/service.js

@@ -0,0 +1,207 @@
+import { and, eq, inArray, isNull, or } from "drizzle-orm";
+import { featureFlags, FLAG_SCOPE_PRECEDENCE } from "../db/schema/index.js";
+import { InvalidInputError, NotFoundError } from "../errors.js";
+import { isInRollout } from "./bucket.js";
+export function createFeaturesService(deps) {
+    function definition(key) {
+        const found = deps.registry.flags[key];
+        if (found === undefined) {
+            /**
+             * Reachable only from untyped JavaScript. Throwing beats defaulting to
+             * `false`: a flag that silently never turns on is far harder to diagnose
+             * than one that fails loudly at the call site.
+             */
+            throw new InvalidInputError(`Unknown feature flag "${key}".`);
+        }
+        return found;
+    }
+    /** Overrides that could apply to this subject, for these keys. */
+    async function loadOverrides(keys, subject) {
+        const targets = [
+            // Global always applies.
+            and(eq(featureFlags.scope, "global")),
+            ...(deps.application !== undefined
+                ? [and(eq(featureFlags.scope, "application"), eq(featureFlags.application, deps.application))]
+                : []),
+            ...(subject.workspaceId !== undefined
+                ? [and(eq(featureFlags.scope, "workspace"), eq(featureFlags.workspaceId, subject.workspaceId))]
+                : []),
+            ...(subject.userId !== undefined
+                ? [and(eq(featureFlags.scope, "user"), eq(featureFlags.userId, subject.userId))]
+                : []),
+        ];
+        return deps.db
+            .select()
+            .from(featureFlags)
+            .where(and(inArray(featureFlags.key, [...keys]), or(...targets)));
+    }
+    /** Apply precedence: the most specific matching override wins. */
+    function decide(key, rows, subject) {
+        const flag = definition(key);
+        const relevant = rows.filter((row) => row.key === key);
+        let winner;
+        let winnerRank = -1;
+        for (const row of relevant) {
+            const rank = FLAG_SCOPE_PRECEDENCE.indexOf(row.scope);
+            if (rank > winnerRank) {
+                winner = row;
+                winnerRank = rank;
+            }
+        }
+        if (winner === undefined) {
+            return {
+                key,
+                enabled: flag.default,
+                variant: flag.default ? flag.defaultVariant : undefined,
+                source: "default",
+            };
+        }
+        /**
+         * Rollout narrows an override; it never turns one on. So a disabled override
+         * stays disabled regardless of percentage, and `rollout: 20` on an enabled
+         * override means "on for 20% of the subjects this override covers".
+         */
+        let enabled = winner.enabled;
+        if (enabled && winner.rolloutPercentage !== null) {
+            // Bucket on the most specific subject available, so a per-user rollout is
+            // stable per user and a per-workspace one is stable per workspace.
+            const subjectId = subject.userId ?? subject.workspaceId;
+            enabled = isInRollout(key, winner.rolloutPercentage, subjectId);
+        }
+        return {
+            key,
+            enabled,
+            // A disabled flag has no variant; see getVariant.
+            variant: enabled ? (winner.variant ?? flag.defaultVariant) : undefined,
+            source: winner.scope,
+        };
+    }
+    function assertTarget(input) {
+        const expectations = {
+            global: undefined,
+            application: "application",
+            workspace: "workspaceId",
+            user: "userId",
+        };
+        const required = expectations[input.scope];
+        if (required !== undefined && input[required] === undefined) {
+            throw new InvalidInputError(`A "${input.scope}" override requires ${String(required)}.`);
+        }
+        // Reject a target that contradicts the scope, rather than silently ignoring
+        // it — `{ scope: "global", workspaceId }` is always a mistake.
+        for (const [scope, field] of Object.entries(expectations)) {
+            if (field !== undefined && scope !== input.scope && input[field] !== undefined) {
+                throw new InvalidInputError(`A "${input.scope}" override must not set ${String(field)}.`);
+            }
+        }
+    }
+    /** Match exactly one target row, treating absent columns as null. */
+    function targetFilter(input) {
+        return and(eq(featureFlags.key, input.key), eq(featureFlags.scope, input.scope), input.application === undefined
+            ? isNull(featureFlags.application)
+            : eq(featureFlags.application, input.application), input.workspaceId === undefined
+            ? isNull(featureFlags.workspaceId)
+            : eq(featureFlags.workspaceId, input.workspaceId), input.userId === undefined
+            ? isNull(featureFlags.userId)
+            : eq(featureFlags.userId, input.userId));
+    }
+    const service = {
+        async resolve(key, subject = {}) {
+            const rows = await loadOverrides([key], subject);
+            return decide(key, rows, subject);
+        },
+        async isEnabled(key, subject = {}) {
+            return (await service.resolve(key, subject)).enabled;
+        },
+        async getVariant(key, subject = {}) {
+            const resolved = await service.resolve(key, subject);
+            return resolved.variant;
+        },
+        async all(subject = {}) {
+            const keys = Object.keys(deps.registry.flags);
+            const rows = keys.length === 0 ? [] : await loadOverrides(keys, subject);
+            const result = new Map();
+            for (const key of keys) {
+                result.set(key, decide(key, rows, subject));
+            }
+            return result;
+        },
+        async set(input) {
+            const flag = definition(input.key);
+            assertTarget(input);
+            if (input.variant != null) {
+                if (flag.variants === undefined) {
+                    throw new InvalidInputError(`Flag "${input.key}" does not declare variants.`);
+                }
+                if (!flag.variants.includes(input.variant)) {
+                    throw new InvalidInputError(`"${input.variant}" is not a declared variant of "${input.key}".`);
+                }
+            }
+            if (input.rolloutPercentage != null) {
+                if (!Number.isInteger(input.rolloutPercentage) ||
+                    input.rolloutPercentage < 0 ||
+                    input.rolloutPercentage > 100) {
+                    throw new InvalidInputError("rolloutPercentage must be an integer between 0 and 100.");
+                }
+            }
+            const values = {
+                key: input.key,
+                scope: input.scope,
+                application: input.application ?? null,
+                workspaceId: input.workspaceId ?? null,
+                userId: input.userId ?? null,
+                enabled: input.enabled,
+                variant: input.variant ?? null,
+                rolloutPercentage: input.rolloutPercentage ?? null,
+                description: input.description ?? null,
+            };
+            const [row] = await deps.db
+                .insert(featureFlags)
+                .values(values)
+                /**
+                 * Idempotent by target. Setting the same override twice updates it rather
+                 * than failing, which is what an admin UI and a seeding script both want.
+                 */
+                .onConflictDoUpdate({
+                target: [
+                    featureFlags.key,
+                    featureFlags.scope,
+                    featureFlags.application,
+                    featureFlags.workspaceId,
+                    featureFlags.userId,
+                ],
+                set: {
+                    enabled: values.enabled,
+                    variant: values.variant,
+                    rolloutPercentage: values.rolloutPercentage,
+                    description: values.description,
+                    updatedAt: new Date(),
+                },
+            })
+                .returning();
+            return row;
+        },
+        async unset(input) {
+            definition(input.key);
+            assertTarget(input);
+            const deleted = await deps.db
+                .delete(featureFlags)
+                .where(targetFilter(input))
+                .returning({ id: featureFlags.id });
+            if (deleted.length === 0) {
+                throw new NotFoundError("Feature flag override not found.");
+            }
+        },
+        async overrides(key) {
+            definition(key);
+            const rows = await deps.db
+                .select()
+                .from(featureFlags)
+                .where(eq(featureFlags.key, key));
+            // Broadest first, matching the order they are applied in.
+            return rows.sort((a, b) => FLAG_SCOPE_PRECEDENCE.indexOf(a.scope) - FLAG_SCOPE_PRECEDENCE.indexOf(b.scope));
+        },
+    };
+    return service;
+}
+//# sourceMappingURL=service.js.map

package/dist/features/service.js.map

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

package/dist/files/index.d.ts

@@ -0,0 +1,6 @@
+import { type FilesService } from "./service.ts";
+export { createFilesService, fileStoragePath, sanitizeFilename, type CreateUploadInput, type DirectUpload, type FilesService, type FilesServiceDeps, type ListFilesOptions, type ServerUploadInput, } from "./service.ts";
+export type { FileRecord, FileStatus } from "../db/schema/files.ts";
+/** Default service, bound to the configured database and object store. */
+export declare const files: FilesService;
+//# sourceMappingURL=index.d.ts.map

package/dist/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAsDA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,YAKlB,CAAC"}

package/dist/files/index.js

@@ -0,0 +1,64 @@
+/**
+ * Public files surface: `@digimuza/saas-core/files`. Server-only.
+ *
+ * The durable record of a stored object: where the bytes are, what they are, who
+ * uploaded them, and whether the upload actually finished.
+ *
+ * It pairs with [`storage`](../storage/README.md), which moves bytes and knows
+ * nothing about rows. The split matters for the direct-upload flow: the server
+ * hands the browser a presigned URL and the bytes travel out-of-band, so there has
+ * to be a row *before* anything is stored and a way to confirm afterwards.
+ *
+ * The core owns the **record**, not the **association**. A product table
+ * references `files.id` to say what a file is *for* — an avatar, an import, an
+ * attachment — because only the product knows.
+ *
+ * ## Direct browser upload
+ *
+ * ```ts
+ * // 1. Reserve. Row is `pending`; nothing treats the file as real yet.
+ * const { file, uploadUrl } = await files.createUpload(context, {
+ *   filename: "quarterly.csv",
+ *   contentType: "text/csv",
+ *   sizeBytes: declaredSize,
+ * });
+ *
+ * // 2. The browser PUTs the bytes to `uploadUrl` directly.
+ *
+ * // 3. Confirm. Asks the store how big the object really is.
+ * const ready = await files.confirmUpload(context, file.id);
+ * ```
+ *
+ * ## Server-side upload
+ *
+ * ```ts
+ * const file = await files.upload(context, {
+ *   filename: "report.pdf",
+ *   body: bytes,
+ *   contentType: "application/pdf",
+ * });
+ * // Already `ready`, with a checksum — the server saw the bytes.
+ * ```
+ *
+ * ## Reading and cleanup
+ *
+ * ```ts
+ * const url = await files.getUrl(context, file.id);   // named, attachment
+ * await files.delete(context, file.id);               // object, then row
+ *
+ * // From a scheduled job: reservations whose upload never happened.
+ * await files.purgeAbandoned();
+ * ```
+ */
+import { getDatabase } from "../db/client.js";
+import { storage } from "../storage/index.js";
+import { createFilesService } from "./service.js";
+export { createFilesService, fileStoragePath, sanitizeFilename, } from "./service.js";
+/** Default service, bound to the configured database and object store. */
+export const files = createFilesService({
+    get db() {
+        return getDatabase();
+    },
+    storage,
+});
+//# sourceMappingURL=index.js.map

package/dist/files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAqB,MAAM,cAAc,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GAOjB,MAAM,cAAc,CAAC;AAItB,0EAA0E;AAC1E,MAAM,CAAC,MAAM,KAAK,GAAiB,kBAAkB,CAAC;IACpD,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,OAAO;CACR,CAAC,CAAC"}