@flytedesk/app-kit 0.1.3 → 0.2.0

package/dist/profile/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Hand-written row/option types for @flytedesk/app-kit/profile.
+ *
+ * Field names here mirror prisma/fragments/profile.prisma's camelCase model fields
+ * (userId/title/phone/timezone/bio/updatedAt) — a consumer's generated PrismaClient,
+ * once they've run `profile-sync init` and their own `prisma generate`, satisfies
+ * ProfileStore directly via `prisma.appKitUserProfile.findUnique` / `.upsert`.
+ */
+export interface ProfileRow {
+    userId: string;
+    title: string | null;
+    phone: string | null;
+    timezone: string | null;
+    bio: string | null;
+    updatedAt: Date;
+}
+/** The self-service fields a caller may write. */
+export type ProfileFields = Pick<ProfileRow, "title" | "phone" | "timezone" | "bio">;
+/** A PATCH body: any subset of ProfileFields, all still required to be strings
+ *  (or absent) once validated — see parsePatchBody in ./plugin.ts. */
+export type ProfilePatch = Partial<ProfileFields>;
+/**
+ * Minimal persistence seam this plugin needs — deliberately NOT a dependency on
+ * `@prisma/client` (this package never builds its own PrismaClient; mirrors why
+ * src/trace/types.ts's TracePrismaClient and src/auth/types.ts's AuthStore are both
+ * ORM-agnostic structural interfaces rather than importing the generated client
+ * type). A consumer's generated PrismaClient trivially satisfies this shape:
+ *
+ *   const store: ProfileStore = {
+ *     findByUserId: (userId) => prisma.appKitUserProfile.findUnique({ where: { userId } }),
+ *     upsert: (userId, patch) =>
+ *       prisma.appKitUserProfile.upsert({
+ *         where: { userId },
+ *         create: { userId, ...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/profile/plugin.test.ts).
+ */
+export interface ProfileStore {
+    /** Must return `null`, not throw/404, when the user has no row yet — a person
+     *  with no profile row still "has a profile," it's just all-null fields. */
+    findByUserId(userId: string): Promise<ProfileRow | null>;
+    /** Upserts the row for `userId`, writing only the fields present in `patch`
+     *  (fields absent from `patch` are left unchanged on an existing row, and null
+     *  on a newly-created one). */
+    upsert(userId: string, patch: ProfilePatch): Promise<ProfileRow>;
+}
+export interface AppKitProfileOptions {
+    /** The persistence seam — see ProfileStore above. Required. */
+    store: ProfileStore;
+    /**
+     * Base path the GET/PATCH routes are mounted under. Default "/profile".
+     *
+     * Deliberately not "/me": @flytedesk/app-kit/auth's own README/index.ts doc
+     * comment illustrates a consumer wiring up `GET /me` themselves, returning
+     * `request.authUser` (identity/roles/permissions — see src/auth/index.ts). That's
+     * a different resource than this plugin's editable title/phone/timezone/bio
+     * fields, so reusing "/me" here would be conceptually confusing even though nothing
+     * actually collides at registration time (auth doesn't register that route itself,
+     * it's just the example a consumer is expected to write).
+     */
+    routePrefix?: string;
+}
+/** What GET/PATCH `{routePrefix}` return. Always 200 — see ProfileStore.findByUserId. */
+export interface ProfileResponseBody {
+    userId: string;
+    title: string | null;
+    phone: string | null;
+    timezone: string | null;
+    bio: string | null;
+    /** ISO 8601, or `null` if the user has no row yet. */
+    updatedAt: string | null;
+}

package/dist/profile/types.js

@@ -0,0 +1,10 @@
+/**
+ * Hand-written row/option types for @flytedesk/app-kit/profile.
+ *
+ * Field names here mirror prisma/fragments/profile.prisma's camelCase model fields
+ * (userId/title/phone/timezone/bio/updatedAt) — a consumer's generated PrismaClient,
+ * once they've run `profile-sync init` and their own `prisma generate`, satisfies
+ * ProfileStore directly via `prisma.appKitUserProfile.findUnique` / `.upsert`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/profile/types.js.map

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

package/package.json

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

package/prisma/fragments/profile.meta.json

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

package/prisma/fragments/profile.prisma

@@ -0,0 +1,42 @@
+// @flytedesk/app-kit/profile — canonical Prisma model fragment (DEC-39, ported to a
+// second fragment for the profile module).
+//
+// This fragment is NOT built into a Prisma Client by this package. It is copied
+// verbatim into the consumer's own multi-file Prisma schema folder by `profile-sync
+// init` (see src/cli/profile-sync.ts, which — like trace-sync — is a thin wrapper
+// around the generalized src/cli/sync-engine.ts), and the consumer generates their
+// own client against their own schema + this fragment merged in.
+//
+// What this models: title/phone/timezone/bio are cross-app, person-level facts —
+// not specific to any one flytedesk product. The first real consumer is
+// flytedesk-id, replacing its own local per-field storage for these with this
+// shared table so other flytedesk apps don't each hand-roll their own GET/PATCH
+// /me route + migration for the same handful of self-service profile fields.
+//
+// Design constraints (deliberate, see DEC-39 — same reasoning as trace.prisma):
+//   - No `@relation`/FK attributes anywhere. `userId` is a plain scalar matching
+//     the consuming app's own user-id type by convention, not a foreign key — a
+//     package that ships models into a consumer's schema cannot see the
+//     consumer's own User model to point a relation at.
+//   - No Prisma `enum`. None of these fields need one today, but the same
+//     schema-global-collision reasoning as trace.prisma applies if one is ever
+//     added here: it would stay a plain `String` column instead.
+//   - `String @id` (not `BigInt @default(autoincrement())`): unlike trace's
+//     high-write append log, this table has exactly one row per user, keyed
+//     directly on the consumer's own user id — no separate surrogate key earns
+//     its keep here.
+//
+// Table name is prefixed `app_kit_` via `@@map` so it can't collide with a
+// consumer's own tables. Column names are snake_case via `@map`, matching the raw
+// SQL in prisma/migrations/0002_app_kit_profile_init/migration.sql exactly.
+
+model AppKitUserProfile {
+  userId    String   @id @map("user_id")
+  title     String?
+  phone     String?
+  timezone  String?
+  bio       String?
+  updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
+
+  @@map("app_kit_user_profile")
+}

package/prisma/migrations/0002_app_kit_profile_init/migration.sql

@@ -0,0 +1,15 @@
+-- @flytedesk/app-kit/profile :: 0002_app_kit_profile_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 on the trace fragment). Column names, types, and defaults match
+-- prisma/fragments/profile.prisma exactly: TEXT for the String @id and the nullable
+-- String columns, TIMESTAMPTZ for DateTime.
+CREATE TABLE app_kit_user_profile (
+  user_id    TEXT PRIMARY KEY,
+  title      TEXT,
+  phone      TEXT,
+  timezone   TEXT,
+  bio        TEXT,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/prisma/migrations/manifest.json

@@ -1,8 +1,16 @@
 [
   {
     "id": "0001_app_kit_trace_init",
+    "fragment": "trace",
     "file": "0001_app_kit_trace_init/migration.sql",
     "checksum": "sha256:413918649af395583a2647f415ae4c8249477a922f1f5e25916742c535253915",
     "introducedInFragmentVersion": "1.0.0"
+  },
+  {
+    "id": "0002_app_kit_profile_init",
+    "fragment": "profile",
+    "file": "0002_app_kit_profile_init/migration.sql",
+    "checksum": "sha256:62d688a2db89c77f12c61a3c98be5cfe84a6e06f8a4dda9d24b0f9acd5511b32",
+    "introducedInFragmentVersion": "1.0.0"
   }
 ]