@intelligo-dev/auth 1.0.0-beta.1 → 1.0.0-beta.14

package/src/onboarding/errors.ts

@@ -1,13 +1,6 @@
 /**
- * Onboarding service error type.
- *
- * Mirrors `../team/errors.ts` and `../workspace/errors.ts`: the
- * onboarding service (./service.ts) throws this for every failure it
- * recognizes rather than returning an ad-hoc `{ success, error }`
- * envelope — that shaping is a transport concern (a Server Action, a
- * route handler) and belongs one layer up, alongside
- * revalidatePath/Sentry/toast/i18n, none of which this package may
- * depend on.
+ * Thrown for every failure the onboarding service recognizes. Shaping it for a UI
+ * (a `{ success, error }` envelope, i18n, revalidation) is the transport's job.
  */
 
 /**
@@ -17,9 +10,7 @@
  * - `not_found` — the caller's `users` row could not be found.
  */
 export type OnboardingServiceErrorCode =
-  | "forbidden"
-  | "invalid_input"
-  | "not_found";
+  "forbidden" | "invalid_input" | "not_found";
 
 export class OnboardingServiceError extends Error {
   readonly code: OnboardingServiceErrorCode;
@@ -33,14 +24,11 @@ export class OnboardingServiceError extends Error {
     this.name = "OnboardingServiceError";
     this.code = code;
     if (options?.cause !== undefined) {
-      // ES2020 target predates the standard `cause` constructor option;
-      // assign it directly so `instanceof Error` consumers (and Node's
-      // own error inspection) still see it.
+      // The ES2020 target predates the `cause` constructor option.
       (this as { cause?: unknown }).cause = options.cause;
     }
 
-    // Restore prototype chain (extending built-ins across some
-    // transpilation targets loses `instanceof`).
+    // Extending built-ins loses `instanceof` on some transpilation targets.
     Object.setPrototypeOf(this, OnboardingServiceError.prototype);
   }
 }

package/src/onboarding/schemas.ts

@@ -1,19 +1,7 @@
 /**
- * Onboarding validation schema.
- *
- * A single generic step-id validator — see the module doc comment on
- * `./service.ts` for why this is a bare, bounded string rather than a
- * product-specific enum. Ignite's original
- * `lib/validations/onboarding.ts` pinned this to
- * `z.enum(["role", "profile", "complete"])`, Career's own 3-step wizard
- * shape. The `users.onboarding_step` column itself is untyped `text`,
- * so that enum was a product-level constraint bolted onto a generic
- * column, not something this shared contract should require. A
- * consumer defines its own step ids (typically the `id` field of a
- * steps-config array it owns) and passes them straight through;
- * Ignite's cut-over copy keeps its own enum-shaped schema at the
- * transport layer if it wants stricter validation than "non-empty,
- * bounded string".
+ * A step id is a non-empty, bounded string, not an enum: step ids are the
+ * consumer's (the `id`s of its own steps config). A consumer wanting
+ * stricter validation keeps its own schema at the transport layer.
  */
 
 import { z } from "zod";

package/src/onboarding/service.ts

@@ -1,56 +1,9 @@
 /**
- * Onboarding service — the durable business rules behind a user's
- * first-run onboarding flow, extracted from the product application's
- * onboarding actions (page/registry migration, `onboarding` family,
- * roadmap item 11).
- *
- * Unlike `../team/service.ts` and `../workspace/service.ts`, this
- * service has no Better-Auth organization-plugin calls to make — it
- * reads and writes exactly two columns on `@intelligo-dev/core`'s `users`
- * table (`onboardingCompleted`, `onboardingStep`) directly via Drizzle.
- *
- * No ports: `complete()` and `skip()` only flip those two columns and
- * return the resulting state — they do NOT provision trial credits,
- * record referrals, or perform any other first-workspace bootstrapping.
- * Ignite's original `completeOnboarding()` action did exactly that
- * (`provisionTrialCredits`/`recordReferralSignup`/`grantReferralUpgrade`
- * inline), but that work belongs to the consumer's own
- * `onWorkspaceCreated` binding instead — see `../workspace-init.ts`'s
- * `onWorkspaceCreated` port and the `app-shell` registry item's
- * `lib/workspace-bootstrap.ts`, which already runs once per new
- * workspace. Duplicating it here would either double-provision (it
- * would fire again on every onboarding completion, not just the first
- * workspace) or force this package to depend on `@intelligo-dev/billing`,
- * which the allowlist in
- * `tests/architecture/dependency-direction.test.ts` forbids.
- *
- * ---------------------------------------------------------------------
- * Why `setStep` takes a bare `string`, not an enum
- * ---------------------------------------------------------------------
- * See the doc comment on `./schemas.ts`'s `setStepSchema`. Short
- * version: the `onboarding_step` column is untyped `text`, and a
- * framework-owned service can't know a consumer's step ids in advance
- * — a different product may have two steps, or six. This module
- * accepts any non-empty string up to 64 characters and persists it
- * verbatim.
- *
- * ---------------------------------------------------------------------
- * Why `skip()` has the same durable effect as `complete()`
- * ---------------------------------------------------------------------
- * The `users` table has no separate "skipped" column, so there is
- * nothing else to persist. Ignite's original `skipOnboarding()` action
- * logged an analytics event and then delegated to `completeOnboarding()`
- * unchanged; this service mirrors that shape as two distinct methods
- * (rather than collapsing `skip` into an alias) so a transport can
- * still log/tag the skip differently before or after calling it —
- * that shaping, like everything else transport-level, does not belong
- * in this service.
- *
- * Authorization (`requireAuth`) lives INSIDE each method, not at the
- * transport. Every recognized failure throws `OnboardingServiceError`
- * with a stable `code` — no revalidatePath/Sentry/next-intl/toast here;
- * that shaping is the transport's job (a Server Action, a route
- * handler).
+ * The caller's first-run onboarding state: two columns on `users`
+ * (`onboardingCompleted`, `onboardingStep`). Completing onboarding has no
+ * trial or credit side effects; first-workspace bootstrapping runs once per
+ * workspace through `ensureUserWorkspace`'s `onWorkspaceCreated`. Each method
+ * authorizes itself and throws `OnboardingServiceError`.
  */
 
 import { eq } from "drizzle-orm";
@@ -88,9 +41,7 @@ export function createOnboardingService() {
     }
   }
 
-  /**
-   * Get the caller's current onboarding state.
-   */
+  /** The caller's current onboarding state. */
   async function getState(): Promise<OnboardingState> {
     const { user } = await callRequireAuth();
 
@@ -114,9 +65,8 @@ export function createOnboardingService() {
   }
 
   /**
-   * Set the caller's current onboarding step. A product defines its
-   * own step ids (see the module doc comment); this only validates
-   * that `step` is a non-empty, bounded string and persists it
+   * Set the caller's current step. Step ids are the product's; this only
+   * checks for a non-empty string of at most 64 characters and persists it
    * verbatim. Does not touch `onboardingCompleted`.
    */
   async function setStep(step: string): Promise<OnboardingState> {
@@ -140,10 +90,7 @@ export function createOnboardingService() {
     return { completed: false, currentStep: parsed.data };
   }
 
-  /**
-   * Mark onboarding complete and clear the step. No trial/referral
-   * side effects — see the module doc comment.
-   */
+  /** Mark onboarding complete and clear the step. */
   async function complete(): Promise<OnboardingState> {
     const { user } = await callRequireAuth();
 
@@ -160,9 +107,8 @@ export function createOnboardingService() {
   }
 
   /**
-   * Skip onboarding. Same durable effect as `complete()` — see the
-   * module doc comment for why this is its own method rather than an
-   * alias.
+   * Skip onboarding. Same durable effect as `complete()` (there is no
+   * "skipped" column); a separate method so a transport can tell them apart.
    */
   async function skip(): Promise<OnboardingState> {
     return complete();

package/src/org-api.ts

@@ -1,62 +1,10 @@
 /**
- * Typed wrapper for Better-Auth organization plugin endpoints.
- *
- * The plugin endpoints (`/organization/...`) are added at runtime by
- * Better-Auth's organization plugin and are not present on the inferred
- * `auth.api` type. Without a wrapper, consumers had to reach for
- * `as any as Record<...>` casts or `@ts-expect-error` comments — both
- * lose all type information.
- *
- * This module declares the explicit input/output shapes for every
- * organization endpoint the team service calls and exposes them under
- * the plugin's HTTP path names (`/organization/invite-member`, etc.),
- * which is the vocabulary the rest of this package's `team/` module
- * uses.
- *
- * (Ported from the product application’s Better-Auth type wrapper as part of the
- * team-settings backend extraction — packages/auth owns the org-api
- * contract now; ignite's copy is retired at cutover.)
- *
- * IMPORTANT — found while wiring the real-DB integration test for this
- * extraction: ignite's original module built `orgApi` as
- * `auth.api as unknown as OrgApi`, i.e. a bare type-cast that assumes
- * `auth.api` is keyed by these HTTP path strings. It is not. Better-Auth's
- * organization plugin (`better-auth@1.6.30`,
- * `plugins/organization/organization.mjs`) exposes each endpoint on
- * `auth.api` under its own camelCase *server* id, which does not always
- * match the path or the *client* SDK name documented alongside it:
- *
- *   path                                  | auth.api key (server) | authClient.organization.* (client)
- *   /organization/invite-member           | createInvitation       | inviteMember
- *   /organization/get-invitation          | getInvitation          | getInvitation
- *   /organization/accept-invitation       | acceptInvitation       | acceptInvitation
- *   /organization/reject-invitation       | rejectInvitation       | rejectInvitation
- *   /organization/cancel-invitation       | cancelInvitation       | cancelInvitation
- *   /organization/remove-member           | removeMember           | removeMember
- *   /organization/update-member-role      | updateMemberRole       | updateMemberRole
- *   /organization/leave                   | leaveOrganization      | leave
- *   /organization/list                    | listOrganizations      | list
- *   /organization/set-active              | setActiveOrganization  | setActive
- *   /organization/list-user-invitations   | listUserInvitations    | listUserInvitations
- *
- * A bare `auth.api as unknown as OrgApi` cast type-checks (TypeScript
- * cannot see through the cast) but throws `TypeError: ... is not a
- * function` at runtime for every call whose row above differs in the
- * first two columns — i.e. invite-member, leave, list, and set-active
- * unconditionally, since their server ids aren't just a casing change
- * of the path. This was invisible in ignite's test suite because
- * `actions/__tests__/team.test.ts` mocks `@/types/better-auth` (the
- * whole `orgApi` object) rather than exercising the cast against a
- * real `auth.api`, and only surfaced once this extraction's
- * `service.integration.test.ts` called the real thing. It is a live
- * bug in ignite's shipped team-management actions today, not a
- * hypothetical — worth a fix there independent of this migration.
- *
- * `orgApi` below is therefore a real object, not a cast: each path key
- * forwards to the correctly-named `auth.api` method. The `OrgApi`
- * type and every call site elsewhere in this package (`team/service.ts`
- * and its tests) are unaffected — they only ever see the path-keyed
- * shape.
+ * Typed access to Better-Auth's organization-plugin endpoints, which the
+ * inferred `auth.api` type does not include. Keys are the plugin's HTTP
+ * paths; each forwards to the plugin's server id, which is not always the
+ * path in camelCase (`/organization/invite-member` is `createInvitation`,
+ * `/organization/list` is `listOrganizations`), so a blanket cast of
+ * `auth.api` would type-check and then throw "is not a function".
  */
 
 import { auth } from "./server";
@@ -160,14 +108,9 @@ export interface OrgApi {
 }
 
 /**
- * `auth.api`'s organization-plugin methods are typed loosely by
- * Better-Auth (broad `Record<string, unknown>`-ish body/query types
- * driven by its own zod schemas) — each is cast to its specific
- * `OrgApi` member signature at the point of use below, which is the
- * same trust boundary the rest of this codebase already accepts for
- * these calls (see the module doc comment above for why a *blanket*
- * cast is not safe: it hides the wrong key entirely, whereas casting
- * per-member here only relaxes the parameter/return types).
+ * Better-Auth types these methods loosely; each is cast to its `OrgApi`
+ * member signature below, which relaxes only parameter and return types,
+ * never which method a key names.
  */
 const api = auth.api as unknown as Record<
   string,

package/src/profile/errors.ts

@@ -1,13 +1,6 @@
 /**
- * Profile service error type.
- *
- * The profile service (./service.ts) throws this for every failure it
- * recognizes rather than returning an ad-hoc `{ success, error }`
- * envelope — that shaping is a transport concern (a Server Action, a
- * route handler) and belongs one layer up, alongside
- * revalidatePath/Sentry/toast/i18n, none of which this package may
- * depend on. Mirrors `TeamServiceError`/`WorkspaceServiceError`
- * (../team/errors.ts, ../workspace/errors.ts).
+ * Thrown for every failure the profile service recognizes. Shaping it for a UI
+ * (a `{ success, error }` envelope, i18n, revalidation) is the transport's job.
  */
 
 /**
@@ -17,9 +10,7 @@
  *   failed (network, upstream API error, etc.).
  */
 export type ProfileServiceErrorCode =
-  | "forbidden"
-  | "invalid_input"
-  | "provider_error";
+  "forbidden" | "invalid_input" | "provider_error";
 
 export interface ProfileServiceErrorMeta {
   [key: string]: unknown;
@@ -39,14 +30,11 @@ export class ProfileServiceError extends Error {
     this.code = code;
     this.meta = options?.meta;
     if (options?.cause !== undefined) {
-      // ES2020 target predates the standard `cause` constructor option;
-      // assign it directly so `instanceof Error` consumers (and Node's
-      // own error inspection) still see it.
+      // The ES2020 target predates the `cause` constructor option.
       (this as { cause?: unknown }).cause = options.cause;
     }
 
-    // Restore prototype chain (extending built-ins across some
-    // transpilation targets loses `instanceof`).
+    // Extending built-ins loses `instanceof` on some transpilation targets.
     Object.setPrototypeOf(this, ProfileServiceError.prototype);
   }
 }

package/src/profile/schemas.ts

@@ -1,13 +1,4 @@
-/**
- * Profile Validation Schemas
- *
- * Zod schemas for user profile updates, shared by the profile service
- * and its transports.
- *
- * (Ported from the product application's `lib/validations/profile.ts` —
- * same semantics: optional name, optional-and-nullable image URL.
- * Ignite's copy is retired at cutover.)
- */
+/** Profile update input, shared by the profile service and its transports. */
 
 import { z } from "zod";
 
@@ -21,3 +12,12 @@ export const updateProfileSchema = z.object({
 });
 
 export type UpdateProfileInput = z.infer<typeof updateProfileSchema>;
+
+/**
+ * A BCP 47 language tag as next-intl routes it ("en", "mn", "pt-BR").
+ * Which tags an app actually ships is the app's `routing.locales`; the
+ * transport checks against that before calling the service.
+ */
+export const preferredLanguageSchema = z
+  .string()
+  .regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/, "Not a language tag");

package/src/profile/service.ts

@@ -1,49 +1,11 @@
 /**
- * Profile management service — the durable business rules behind
- * reading the caller's own profile, updating it, and deleting the
- * account, extracted from the product application's profile actions
- * (page/registry migration, `profile-settings` family, roadmap item 9).
- *
- * Mirrors `createTeamService(ports)` / `createWorkspaceService(ports)`
- * (../team/service.ts, ../workspace/service.ts) one directory over: a
- * factory over optional ports, so this package's allowlisted dependency
- * (`@intelligo-dev/core` only — see
- * tests/architecture/dependency-direction.test.ts) never grows to
- * include an email-sending concern of its own. A consumer binds the
- * account-deletion confirmation email in at its composition root:
- *
- *   const profileService = createProfileService({
- *     onAccountDeleted: ({ email, name }) =>
- *       sendEmail({ to: email, subject: ..., html: ... }), // @intelligo-dev/core/email
- *   });
- *
- * Authorization (`requireAuth`) lives INSIDE each method, not at the
- * transport. Every recognized failure throws `ProfileServiceError` with
- * a stable `code` — no revalidatePath/Sentry/next-intl/toast here; that
- * shaping is the transport's job (a Server Action, a route handler).
- *
- * ---------------------------------------------------------------------
- * Why the confirmation email is a port, not a direct import
- * ---------------------------------------------------------------------
- * The product application's original `deleteAccount()`
- * calls `sendEmail` from
- * `@intelligo-dev/core/email` directly, inline, with a hardcoded English
- * HTML template. `@intelligo-dev/auth` already imports `@intelligo-dev/core/email`
- * elsewhere (`server.ts`'s Better-Auth hooks — verification, password
- * reset, welcome, invitation emails), so nothing in the allowlist
- * (auth → core only) would technically block importing `sendEmail`
- * here too. The port exists anyway, for the same reason
- * `TeamServicePorts.sendInvitationEmail` and
- * `WorkspaceServicePorts.checkWorkspaceLimit` are ports rather than
- * direct calls: this service should not own *content* — copy, subject
- * lines, template shape — for a side effect a consumer may want to
- * localize, skip, or replace with a different provider. `onAccountDeleted`
- * is fire-and-forget by design (matching ignite's `.catch(console.error)`
- * pattern): a failed confirmation email must never block the deletion
- * that already succeeded.
+ * The caller's own profile: read, update, delete the account. Each method
+ * authorizes itself and throws `ProfileServiceError`. The confirmation email
+ * is the `onAccountDeleted` port so its copy and provider stay the
+ * consumer's; it is fire-and-forget, since the deletion has already succeeded.
  */
 
-import { headers } from "next/headers";
+import { getRequestHeaders } from "@intelligo-dev/core/request-context";
 import type { ZodType } from "zod";
 import { eq } from "drizzle-orm";
 import { createLogger } from "@intelligo-dev/core/logger";
@@ -52,7 +14,11 @@ import { users, sessions } from "@intelligo-dev/core/db/schema";
 
 import { auth } from "../server";
 import { requireAuth } from "../helpers";
-import { updateProfileSchema, type UpdateProfileInput } from "./schemas";
+import {
+  preferredLanguageSchema,
+  updateProfileSchema,
+  type UpdateProfileInput,
+} from "./schemas";
 import { ProfileServiceError, isProfileServiceError } from "./errors";
 
 const log = createLogger("ProfileService");
@@ -114,9 +80,7 @@ export function createProfileService(ports: ProfileServicePorts = {}) {
     }
   }
 
-  /**
-   * Get the caller's own profile.
-   */
+  /** The caller's own profile. */
   async function getProfile(): Promise<ProfileRecord> {
     const { user } = await callRequireAuth();
 
@@ -133,13 +97,12 @@ export function createProfileService(ports: ProfileServicePorts = {}) {
    * Update the caller's own name/image via the Better-Auth user API.
    * Only the fields present in `input` are sent — omitting a field
    * leaves it unchanged; `image: null` is dropped rather than forwarded
-   * (Better-Auth's `updateUser` does not accept `null`), matching
-   * ignite's original action.
+   * (Better-Auth's `updateUser` does not accept `null`).
    */
   async function updateProfile(input: UpdateProfileInput): Promise<void> {
     await callRequireAuth();
     const validated = parseInput(updateProfileSchema, input);
-    const hdrs = await headers();
+    const hdrs = await getRequestHeaders();
 
     const updateData: { name?: string; image?: string } = {};
     if (validated.name !== undefined) updateData.name = validated.name;
@@ -159,6 +122,31 @@ export function createProfileService(ports: ProfileServicePorts = {}) {
     }
   }
 
+  /**
+   * Record the caller's preferred language (`users.preferred_language`),
+   * which emails and a returning session's default locale read. A column
+   * Intelligo owns rather than a Better-Auth user field, so it is written
+   * directly.
+   */
+  async function setPreferredLanguage(locale: string): Promise<void> {
+    const { user } = await callRequireAuth();
+    const validated = parseInput(preferredLanguageSchema, locale);
+
+    try {
+      await db
+        .update(users)
+        .set({ preferredLanguage: validated, updatedAt: new Date() })
+        .where(eq(users.id, user.id));
+    } catch (error) {
+      log.error("setPreferredLanguage failed", { error: errorMessage(error) });
+      throw new ProfileServiceError(
+        "provider_error",
+        "Failed to update the preferred language",
+        { cause: error }
+      );
+    }
+  }
+
   /**
    * Delete the caller's own account: soft delete (`users.deletedAt`),
    * invalidate every session (force logout), then fire the
@@ -201,6 +189,7 @@ export function createProfileService(ports: ProfileServicePorts = {}) {
   return {
     getProfile,
     updateProfile,
+    setPreferredLanguage,
     deleteAccount,
   };
 }

package/src/roles.ts

@@ -1,9 +1,6 @@
 /**
- * The platform role.
- *
- * Deliberately a separate module from helpers.ts and server.ts: both
- * need the constant, and server.ts (the Better-Auth instance) cannot
- * import helpers.ts, which imports server.ts.
+ * Its own module because server.ts and helpers.ts both need it, and
+ * server.ts cannot import helpers.ts, which imports server.ts.
  */
 
 /**
@@ -15,3 +12,37 @@
  * on it is gated on nothing.
  */
 export const PLATFORM_ADMIN_ROLE = "platform-admin";
+
+/**
+ * Where a user stands as a platform admin: `hasRole` reads `users.role`
+ * (comma-separated), `allowlisted` reads PLATFORM_ADMIN_EMAILS, the
+ * bootstrap that `requirePlatformAdmin` promotes into the column.
+ *
+ * The allowlist names an address, so it counts only once the address
+ * is verified: otherwise whoever registers an allowlisted address
+ * first — before the real admin, or on a deployment that sends no
+ * verification mail — would become an admin.
+ */
+export function platformAdminStanding(user: {
+  email?: string | null;
+  emailVerified?: boolean | null;
+  role?: string | null;
+}): { allowlisted: boolean; hasRole: boolean; roles: string[] } {
+  const allowlist = (process.env.PLATFORM_ADMIN_EMAILS ?? "")
+    .split(",")
+    .map((e) => e.trim().toLowerCase())
+    .filter(Boolean);
+
+  const email = user.email?.toLowerCase();
+  const roles = (user.role ?? "")
+    .split(",")
+    .map((r) => r.trim())
+    .filter(Boolean);
+
+  return {
+    allowlisted:
+      !!email && user.emailVerified === true && allowlist.includes(email),
+    hasRole: roles.includes(PLATFORM_ADMIN_ROLE),
+    roles,
+  };
+}