@frigear-nu/preferences 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @frigear-nu/preferences
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed per-user preferences that modules and the host app register with `definePreferences`, stored in one JSON column
+on `users`, and optionally forwarded to OAuth applications as claims.
+
+```ts
+// shared/preferences.ts
+import { z } from 'zod'
+import { definePreferences } from '@frigear-nu/preferences/define'
+
+export default definePreferences({
+  compactTables: z.boolean(),
+  colorMode: { schema: z.enum(['light', 'dark', 'system']), claim: 'color_mode' },
+})
+```
+
+`useUserPreferences()` on the client and `getUserPreference(user, key)` on the server are typed from those schemas.
+See the [documentation](https://docs.frigear.dev/modules/preferences).

package/dist/module.d.mts

@@ -0,0 +1,27 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export { PreferenceDefinition, PreferenceDefinitions, PreferencesOf } from '../dist/runtime/define.js';
+
+type ModuleOptions = {
+    /**
+     * Files that default-export `definePreferences({...})`, resolved from the project root. A `shared/preferences.ts`
+     * is picked up on its own. Other modules register theirs with `addUserPreferences`.
+     */
+    definitions?: string | string[];
+};
+/**
+ * The preferences of a user, keyed by name. This is filled in by the generated types from every registered
+ * definer file, so `preferences.colorMode` is `'light' | 'dark' | 'system' | undefined` and a misspelled key
+ * does not compile.
+ */
+interface UserPreferences {
+}
+
+declare module 'nuxt/schema' {
+    interface NuxtConfig {
+        preferences?: ModuleOptions;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions, UserPreferences };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/preferences",
+  "configKey": "preferences",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineNuxtModule, createResolver, addServerTemplate, addTypeTemplate, addServerImportsDir, addImports, addServerHandler, hasNuxtModule, addServerPlugin } from '@nuxt/kit';
+import { registerModule, extendDatabaseTable } from '@frigear-nu/module-kit/utils';
+
+const module$1 = defineNuxtModule({
+  meta: { name: "@frigear-nu/preferences", configKey: "preferences" },
+  defaults: {},
+  moduleDependencies: {
+    "@nuxthub/core": { version: ">=0.10" },
+    "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/auth": { version: ">=0.0.1" },
+    "@frigear-nu/users": { version: ">=0.0.1" },
+    // Only needed to forward preferences as claims; listed so it is installed before this module is set up.
+    "@frigear-nu/oauth-server": { version: ">=0.0.1", optional: true }
+  },
+  async setup(options, nuxt) {
+    registerModule("@frigear-nu/preferences", nuxt);
+    const resolver = createResolver(import.meta.url);
+    extendDatabaseTable(nuxt, {
+      name: "users",
+      resolver,
+      file: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    const collectSources = async () => {
+      const configured = [options.definitions ?? []].flat();
+      const conventional = join(nuxt.options.rootDir, "shared/preferences.ts");
+      const paths = [
+        ...await Promise.all(configured.map((path) => resolver.resolvePath(path, { cwd: nuxt.options.rootDir }))),
+        ...!configured.length && existsSync(conventional) ? [conventional] : []
+      ];
+      const sources = paths.map((path) => ({ path }));
+      await nuxt.callHook("preferences:definitions", sources);
+      return [...new Map(sources.map((source) => [source.path, source])).values()];
+    };
+    addServerTemplate({
+      filename: "#preferences/definitions",
+      getContents: async () => {
+        const sources = await collectSources();
+        return [
+          ...sources.map((source, index) => `import definitions${index} from ${JSON.stringify(source.path)}`),
+          `export const definitions = [${sources.map((_, index) => `definitions${index}`).join(", ")}]`
+        ].join("\n");
+      }
+    });
+    addTypeTemplate({
+      filename: "types/preferences.d.ts",
+      getContents: async () => {
+        const sources = await collectSources();
+        const extend = sources.length ? ` extends ${sources.map((source) => `PreferencesOf<typeof import(${JSON.stringify(source.path)}).default>`).join(", ")}` : "";
+        return `import type { PreferencesOf } from '${resolver.resolve("./runtime/define")}'
+import type { UserPreferences as RegisteredPreferences } from '@frigear-nu/preferences'
+
+declare module '@frigear-nu/preferences' {
+  interface UserPreferences${extend} {}
+}
+declare module '#auth-utils' {
+  interface User {
+    preferences?: RegisteredPreferences
+  }
+}
+declare module '#preferences/definitions' {
+  export const definitions: Array<import('${resolver.resolve("./runtime/define")}').PreferenceDefinitions>
+}
+`;
+      }
+    }, { nitro: true, nuxt: true });
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addImports({ name: "useUserPreferences", from: resolver.resolve("./runtime/app/composables/useUserPreferences") });
+    addServerHandler({
+      route: "/api/preferences",
+      method: "patch",
+      handler: resolver.resolve("./runtime/server/routes/preferences.patch")
+    });
+    if (hasNuxtModule("@frigear-nu/oauth-server")) {
+      addServerPlugin(resolver.resolve("./runtime/server/plugins/oauth-claims"));
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/composables/index.d.ts

@@ -0,0 +1 @@
+export * from './useUserPreferences.js';

package/dist/runtime/app/composables/index.js

@@ -0,0 +1 @@
+export * from "./useUserPreferences.js";

package/dist/runtime/app/composables/useUserPreferences.d.ts

@@ -0,0 +1,13 @@
+import type { UserPreferences } from '../../../types.js';
+/**
+ * The signed-in user's preferences, typed from every registered definer file.
+ *
+ *     const { preferences, set } = useUserPreferences()
+ *     await set('colorMode', 'dark')
+ */
+export declare const useUserPreferences: () => {
+    preferences: any;
+    get: <K extends keyof UserPreferences>(key: K) => UserPreferences[K] | undefined;
+    set: <K extends keyof UserPreferences>(key: K, value: UserPreferences[K] | null) => Promise<void>;
+    pending: any;
+};

package/dist/runtime/app/composables/useUserPreferences.js

@@ -0,0 +1,18 @@
+export const useUserPreferences = () => {
+  const { user, fetch: refreshSession } = useUserSession();
+  const pending = ref(false);
+  const preferences = computed(() => user.value?.preferences ?? {});
+  function get(key) {
+    return preferences.value[key];
+  }
+  async function set(key, value) {
+    pending.value = true;
+    try {
+      await $fetch("/api/preferences", { method: "PATCH", body: { [key]: value } });
+      await refreshSession();
+    } finally {
+      pending.value = false;
+    }
+  }
+  return { preferences, get, set, pending };
+};

package/dist/runtime/define.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+/**
+ * One preference: a zod schema, or a schema plus how it is exposed.
+ *
+ * - `claim` forwards the value to OAuth applications under that claim name (ID token and `userinfo`).
+ *   Nothing is forwarded without it, so a preference stays private to this app unless it opts in.
+ * - `scope` is the OAuth scope an application must have been granted to receive the claim (default `profile`).
+ */
+export type PreferenceDefinition<S extends z.ZodType = z.ZodType> = S | {
+    schema: S;
+    claim?: string;
+    scope?: string;
+};
+export type PreferenceDefinitions = Record<string, PreferenceDefinition>;
+/** The schema of a definition, whichever of the two shapes it was written in. */
+export type PreferenceSchema<D> = D extends z.ZodType ? D : D extends {
+    schema: infer S extends z.ZodType;
+} ? S : never;
+/** `{ key: value }` as the preferences of a user: every key is optional because a user may not have chosen yet. */
+export type PreferencesOf<T extends PreferenceDefinitions> = {
+    [K in keyof T]?: z.output<PreferenceSchema<T[K]>>;
+};
+/**
+ * Declares preferences. A definer file default-exports the result, and is registered with
+ * `addUserPreferences(nuxt, { path })` or listed in the module's `definitions` option. Its keys and value types
+ * become `UserPreferences`, so the schema is the single source of truth for validation and typing.
+ *
+ *     // shared/preferences.ts
+ *     export default definePreferences({
+ *       // plain schema: stored and readable by this app only
+ *       compactTables: z.boolean(),
+ *       // forwarded to OAuth applications as `color_mode`
+ *       colorMode: { schema: z.enum(['light', 'dark', 'system']), claim: 'color_mode' },
+ *     })
+ */
+export declare const definePreferences: <const T extends PreferenceDefinitions>(definitions: T) => T;

package/dist/runtime/define.js

@@ -0,0 +1 @@
+export const definePreferences = (definitions) => definitions;

package/dist/runtime/server/db/schema.sqlite.d.ts

@@ -0,0 +1,26 @@
+export declare const users: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "users";
+    schema: undefined;
+    columns: {
+        preferences: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "preferences";
+            tableName: "users";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: Record<string, unknown>;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+    };
+    dialect: "sqlite";
+}>;

package/dist/runtime/server/db/schema.sqlite.js

@@ -0,0 +1,4 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const users = sqliteTable("users", {
+  preferences: text("preferences", { mode: "json" }).$type()
+});

package/dist/runtime/server/plugins/oauth-claims.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugins/oauth-claims.js

@@ -0,0 +1,10 @@
+import { preferenceClaims } from "../../utils/registry.js";
+export default defineNitroPlugin((nitro) => {
+  const hooks = nitro.hooks;
+  hooks.hook("oauth:claims", (ctx) => {
+    const claims = preferenceClaims(getPreferenceRegistry(), ctx.user.preferences, ctx);
+    for (const [name, value] of Object.entries(claims)) {
+      if (!(name in ctx.claims)) ctx.claims[name] = value;
+    }
+  });
+});

package/dist/runtime/server/routes/preferences.patch.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/preferences.patch.js

@@ -0,0 +1,17 @@
+import { db, schema } from "@nuxthub/db";
+import { eq } from "drizzle-orm";
+import { parsePreferencePatch } from "../../utils/registry.js";
+export default defineEventHandler(async (event) => {
+  const user = await requireUser(event, { sessionOnly: true });
+  const patch = parsePreferencePatch(getPreferenceRegistry(), await readBody(event));
+  if (!patch.ok) throw createError({ statusCode: 400, statusMessage: patch.message });
+  const [current] = await db.select({ preferences: schema.users.preferences }).from(schema.users).where(eq(schema.users.id, user.id)).limit(1);
+  if (!current) throw createError({ statusCode: 404, statusMessage: "User not found." });
+  const preferences = Object.fromEntries(
+    Object.entries({ ...current.preferences, ...patch.set }).filter(([key]) => !patch.remove.includes(key))
+  );
+  const [updated] = await db.update(schema.users).set({ preferences }).where(eq(schema.users.id, user.id)).returning();
+  if (!updated) throw createError({ statusCode: 404, statusMessage: "User not found." });
+  await setUserSession(event, { user: mapUserToSession(updated) });
+  return preferences;
+});

package/dist/runtime/server/utils/preferences.d.ts

@@ -0,0 +1,13 @@
+import type { UserPreferences } from '../../../types.js';
+import type { ResolvedPreference } from '../../utils/registry.js';
+/** Every registered preference, keyed by name. */
+export declare function getPreferenceRegistry(): Map<string, ResolvedPreference>;
+/**
+ * A typed preference of a user (the session user or a database row), or `undefined` when it was never set or no
+ * longer satisfies its schema.
+ *
+ *     getUserPreference(user, 'colorMode') // 'light' | 'dark' | 'system' | undefined
+ */
+export declare function getUserPreference<K extends keyof UserPreferences & string>(user: {
+    preferences?: unknown;
+} | null | undefined, key: K): UserPreferences[K] | undefined;

package/dist/runtime/server/utils/preferences.js

@@ -0,0 +1,9 @@
+import { definitions } from "#preferences/definitions";
+import { readPreference, resolvePreferences } from "../../utils/registry.js";
+let registry;
+export function getPreferenceRegistry() {
+  return registry ??= resolvePreferences(definitions);
+}
+export function getUserPreference(user, key) {
+  return readPreference(getPreferenceRegistry(), user?.preferences, key);
+}

package/dist/runtime/utils/build.d.ts

@@ -0,0 +1,17 @@
+import type { Nuxt } from '@nuxt/schema';
+export interface PreferenceDefinitionSource {
+    /** Absolute path to a file that default-exports `definePreferences({...})`. */
+    path: string;
+}
+declare module '@nuxt/schema' {
+    interface NuxtHooks {
+        'preferences:definitions': (sources: PreferenceDefinitionSource[]) => void | Promise<void>;
+    }
+}
+/**
+ * Register a definer file. Its keys become part of `UserPreferences`, are validated by the preferences API, and
+ * forwarded as OAuth claims where the definition says so.
+ *
+ *     addUserPreferences(nuxt, { path: resolver.resolve('./runtime/preferences') })
+ */
+export declare function addUserPreferences(nuxt: Nuxt, source: PreferenceDefinitionSource): void;

package/dist/runtime/utils/build.js

@@ -0,0 +1,5 @@
+export function addUserPreferences(nuxt, source) {
+  nuxt.hook("preferences:definitions", (sources) => {
+    sources.push(source);
+  });
+}

package/dist/runtime/utils/registry.d.ts

@@ -0,0 +1,32 @@
+import type { z } from 'zod';
+import type { PreferenceDefinitions } from '../define.js';
+export interface ResolvedPreference {
+    key: string;
+    schema: z.ZodType;
+    /** Name of the OAuth claim the value is forwarded as, if any. */
+    claim?: string;
+    /** Scope an application needs to receive the claim. */
+    scope: string;
+}
+/** Flattens the registered definer files into one lookup. The same key in two files is a mistake worth failing on. */
+export declare function resolvePreferences(sources: PreferenceDefinitions[]): Map<string, ResolvedPreference>;
+export type PreferencePatchResult = {
+    ok: true;
+    set: Record<string, unknown>;
+    remove: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Validates a partial update: every key must be registered, a value must satisfy its schema, and `null` clears
+ * the preference.
+ */
+export declare function parsePreferencePatch(registry: Map<string, ResolvedPreference>, body: unknown): PreferencePatchResult;
+/** The stored value when it still satisfies the schema, so a changed schema never leaks stale data. */
+export declare function readPreference(registry: Map<string, ResolvedPreference>, stored: unknown, key: string): unknown;
+/** The claims to add for a token: only preferences that opted in, only when the scope was granted. */
+export declare function preferenceClaims(registry: Map<string, ResolvedPreference>, stored: unknown, ctx: {
+    tokenType: string;
+    scope: string[];
+}): Record<string, unknown>;

package/dist/runtime/utils/registry.js

@@ -0,0 +1,45 @@
+const isSchema = (value) => typeof value?.safeParse === "function";
+export function resolvePreferences(sources) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    for (const [key, definition] of Object.entries(source)) {
+      if (registry.has(key)) throw new Error(`[preferences] "${key}" is defined more than once.`);
+      const resolved = isSchema(definition) ? { key, schema: definition, scope: "profile" } : { key, schema: definition.schema, claim: definition.claim, scope: definition.scope ?? "profile" };
+      registry.set(key, resolved);
+    }
+  }
+  return registry;
+}
+export function parsePreferencePatch(registry, body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, message: "Expected an object of preferences." };
+  const set = {};
+  const remove = [];
+  for (const [key, value] of Object.entries(body)) {
+    const definition = registry.get(key);
+    if (!definition) return { ok: false, message: `Unknown preference "${key}".` };
+    if (value === null) {
+      remove.push(key);
+      continue;
+    }
+    const parsed = definition.schema.safeParse(value);
+    if (!parsed.success) return { ok: false, message: `Invalid value for "${key}".` };
+    set[key] = parsed.data;
+  }
+  return { ok: true, set, remove };
+}
+export function readPreference(registry, stored, key) {
+  const definition = registry.get(key);
+  if (!definition || !stored || typeof stored !== "object" || !(key in stored)) return void 0;
+  const parsed = definition.schema.safeParse(stored[key]);
+  return parsed.success ? parsed.data : void 0;
+}
+export function preferenceClaims(registry, stored, ctx) {
+  if (ctx.tokenType === "access_token") return {};
+  const claims = {};
+  for (const definition of registry.values()) {
+    if (!definition.claim || !ctx.scope.includes(definition.scope)) continue;
+    const value = readPreference(registry, stored, definition.key);
+    if (value !== void 0) claims[definition.claim] = value;
+  }
+  return claims;
+}

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { type PreferenceDefinition, type PreferenceDefinitions, type PreferencesOf } from '../dist/runtime/define.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions, type UserPreferences } from './module.mjs'

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@frigear-nu/preferences",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Typed per-user preferences that modules and the host app register, stored on the user and optionally forwarded to OAuth applications as claims.",
+  "homepage": "https://docs.frigear.dev/modules/preferences",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/preferences"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/build.d.ts",
+      "import": "./dist/runtime/utils/build.js"
+    },
+    "./define": {
+      "types": "./dist/runtime/define.d.ts",
+      "import": "./dist/runtime/define.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@frigear-nu/auth": "0.0.2",
+    "@frigear-nu/module-kit": "0.1.6",
+    "@frigear-nu/users": "1.0.8",
+    "@libsql/client": "^0.18.0",
+    "@nuxt/kit": "^4.6.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@frigear-nu/oauth-server": ">=0.0.1",
+    "@nuxthub/core": "^0.10.8"
+  },
+  "peerDependenciesMeta": {
+    "@frigear-nu/oauth-server": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@frigear-nu/oauth-server": "0.0.7",
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@nuxthub/core": "^0.10.8",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd test/fixtures/basic && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }