@tuturuuu/utils 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## [0.15.0](https://github.com/tutur3u/platform/compare/utils-v0.14.0...utils-v0.15.0) (2026-07-11)
+
+
+### Features
+
+* **contacts:** migrate users attendance; add satellite-safe workspace-user link helper ([8f53453](https://github.com/tutur3u/platform/commit/8f534533793af8d25e7c2eca6e0147e459d78bbe))
+* **contacts:** migrate users topic-announcements module ([01e19ab](https://github.com/tutur3u/platform/commit/01e19ab60461ccd94a0374bed74ce6e4d5d38a3b))
+* **contacts:** scaffold contacts.tuturuuu.com satellite shell + monorepo registration ([7e335fc](https://github.com/tutur3u/platform/commit/7e335fc036c4a45ed189095ecd10a43ee002294b))
+* **infrastructure:** add abuse protection controls ([0e09692](https://github.com/tutur3u/platform/commit/0e09692a553cb10fbbb521e921951c2a6863281d))
+* **infrastructure:** add rate-limit appeals ([f1e50e9](https://github.com/tutur3u/platform/commit/f1e50e9fd805dca6c80da8daab60ed24199f24ab))
+* **pay:** scaffold apps/pay satellite (pay.tuturuuu.com, port 7826) ([3d6e45c](https://github.com/tutur3u/platform/commit/3d6e45cca6a315fe67213e438144b73103bae2f5))
+* **tools:** add apps/tools public tools app, remove apps/qr ([204aae8](https://github.com/tutur3u/platform/commit/204aae89a04b4163f2859561f8e832526642e271))
+
+
+### Bug Fixes
+
+* **auth:** share account preference cookies ([8c1848a](https://github.com/tutur3u/platform/commit/8c1848a941c1b3f91337104c975e4bc0d8f68fc9))
+* **ci:** keep cache components enabled in production ([75e6e2b](https://github.com/tutur3u/platform/commit/75e6e2bbbf6fa432bc496ee95b75ade5f8847f9f))
+* **cli:** preserve markdown tables in task descriptions ([9faf8ba](https://github.com/tutur3u/platform/commit/9faf8ba44b92565a9dfc2949c496654fc1fea9b3))
+* **infrastructure:** default docker web to native builds ([7d89f00](https://github.com/tutur3u/platform/commit/7d89f004f75ab12eddc3cb92df5a1e6a7255fe0d))
+* **infrastructure:** restore canonical auth host access ([9f6715f](https://github.com/tutur3u/platform/commit/9f6715fb1c5a89598556cba33b16938b76995fc6))
+* restore apps launcher categories ([5c5b571](https://github.com/tutur3u/platform/commit/5c5b571ce920013bcfa5f327c4bb208ea9fbf23e))
+* **satellite:** widen apps launcher grid ([90e3106](https://github.com/tutur3u/platform/commit/90e31066830f535a7fdd0f7bc249e5bc8b273cfc))
+* **security:** limit auth recovery code attempts ([72d454c](https://github.com/tutur3u/platform/commit/72d454c507b0d4b7e69c7b38ad2099dbb83193b2))
+* **tasks:** route native personal task moves normally ([5bbba3c](https://github.com/tutur3u/platform/commit/5bbba3c3f193e722cc87cdfe2eb2734f61442cd0))
+* update launchable app catalog ([cb31207](https://github.com/tutur3u/platform/commit/cb312076aee227de9a8f99105d681911d14a63ac))
+* **web:** fail open without redis ([74bfcc7](https://github.com/tutur3u/platform/commit/74bfcc7ea5f188a56f49802c6a48bde0b109e02d))
+
+
+### Performance Improvements
+
+* **ci:** enable repository-wide remote caching ([6250f91](https://github.com/tutur3u/platform/commit/6250f91d745ef987a4fc86c797aedf41542f421b))
+
+## [0.14.0](https://github.com/tutur3u/platform/compare/utils-v0.13.0...utils-v0.14.0) (2026-07-11)
+
+
+### Features
+
+* **contacts:** migrate users attendance; add satellite-safe workspace-user link helper ([8f53453](https://github.com/tutur3u/platform/commit/8f534533793af8d25e7c2eca6e0147e459d78bbe))
+* **contacts:** migrate users topic-announcements module ([01e19ab](https://github.com/tutur3u/platform/commit/01e19ab60461ccd94a0374bed74ce6e4d5d38a3b))
+* **contacts:** scaffold contacts.tuturuuu.com satellite shell + monorepo registration ([7e335fc](https://github.com/tutur3u/platform/commit/7e335fc036c4a45ed189095ecd10a43ee002294b))
+* **pay:** scaffold apps/pay satellite (pay.tuturuuu.com, port 7826) ([3d6e45c](https://github.com/tutur3u/platform/commit/3d6e45cca6a315fe67213e438144b73103bae2f5))
+
+
+### Bug Fixes
+
+* **auth:** share account preference cookies ([8c1848a](https://github.com/tutur3u/platform/commit/8c1848a941c1b3f91337104c975e4bc0d8f68fc9))
+* restore apps launcher categories ([5c5b571](https://github.com/tutur3u/platform/commit/5c5b571ce920013bcfa5f327c4bb208ea9fbf23e))
+* **satellite:** widen apps launcher grid ([90e3106](https://github.com/tutur3u/platform/commit/90e31066830f535a7fdd0f7bc249e5bc8b273cfc))
+* update launchable app catalog ([cb31207](https://github.com/tutur3u/platform/commit/cb312076aee227de9a8f99105d681911d14a63ac))
+
+
+### Performance Improvements
+
+* **ci:** enable repository-wide remote caching ([6250f91](https://github.com/tutur3u/platform/commit/6250f91d745ef987a4fc86c797aedf41542f421b))
+
 ## [0.13.0](https://github.com/tutur3u/platform/compare/utils-v0.12.1...utils-v0.13.0) (2026-07-05)
 
 

package/biome.json

@@ -1,5 +1,5 @@
 {
   "root": false,
-  "$schema": "https://biomejs.dev/schemas/2.5.1/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
   "extends": "//"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuturuuu/utils",
   "license": "MIT",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tutur3u/platform",
@@ -20,11 +20,11 @@
     "@noble/ciphers": "^2.2.0",
     "@noble/hashes": "^2.2.0",
     "@tanstack/react-query": "^5.101.2",
-    "@tiptap/core": "3.27.1",
-    "@tiptap/react": "3.27.1",
+    "@tiptap/core": "3.27.3",
+    "@tiptap/react": "3.27.3",
     "@tuturuuu/google": "0.0.3",
     "@tuturuuu/icons": "0.0.6",
-    "@tuturuuu/internal-api": "0.14.1",
+    "@tuturuuu/internal-api": "0.17.0",
     "@tuturuuu/supabase": "0.4.0",
     "@upstash/ratelimit": "^2.0.8",
     "@upstash/redis": "^1.38.0",
@@ -35,7 +35,7 @@
     "effect": "^3.21.4",
     "moment": "^2.30.1",
     "next": "^16.3.0-preview.5",
-    "prosemirror-model": "^1.25.9",
+    "prosemirror-model": "^1.25.11",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "tailwind-merge": "^3.6.0",
@@ -45,15 +45,15 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@tuturuuu/types": "0.14.0",
+    "@tuturuuu/types": "0.16.0",
     "@tuturuuu/typescript-config": "0.1.1",
     "@types/diff": "^8.0.0",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "@vitejs/plugin-react": "^6.0.3",
-    "typescript": "7.0.1-rc",
-    "vite": "^8.1.2",
-    "vitest": "^4.1.9"
+    "typescript": "7.0.2",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
   },
   "exports": {
     "./timezones": "./src/timezones.json",

package/src/__tests__/app-url.test.ts

@@ -231,6 +231,7 @@ describe('getLocalInternalAppUrl', () => {
     ['cms', 'https://cms.tuturuuu.localhost'],
     ['calendar', 'https://calendar.tuturuuu.localhost'],
     ['chat', 'https://chat.tuturuuu.localhost'],
+    ['docs', 'https://docs.tuturuuu.localhost'],
     ['drive', 'https://drive.tuturuuu.localhost'],
     ['qr', 'https://qr.tuturuuu.localhost'],
     ['tools', 'https://tools.tuturuuu.localhost'],
@@ -290,6 +291,8 @@ describe('Portless app origin registry', () => {
       'https://calendar.tuturuuu.localhost',
       'https://chat.tuturuuu.localhost',
       'https://cms.tuturuuu.localhost',
+      'https://contacts.tuturuuu.localhost',
+      'https://docs.tuturuuu.localhost',
       'https://drive.tuturuuu.localhost',
       'https://external.tuturuuu.localhost',
       'https://finance.tuturuuu.localhost',
@@ -302,6 +305,7 @@ describe('Portless app origin registry', () => {
       'https://meet.tuturuuu.localhost',
       'https://mind.tuturuuu.localhost',
       'https://nova.tuturuuu.localhost',
+      'https://pay.tuturuuu.localhost',
       'https://tuturuuu.localhost',
       'https://playground.tuturuuu.localhost',
       'https://qr.tuturuuu.localhost',

package/src/calendar-settings-resolver.ts

@@ -0,0 +1,200 @@
+/**
+ * Calendar Settings Resolver
+ *
+ * Implements priority system for calendar preferences:
+ * User settings > Workspace settings > Auto-detection
+ */
+
+type FirstDayOfWeek = 'auto' | 'sunday' | 'monday' | 'saturday';
+
+interface CalendarSettings {
+  timezone: string;
+  firstDayOfWeek: FirstDayOfWeek;
+  timeFormat: '12h' | '24h';
+}
+
+export interface CalendarUserSettings {
+  timezone?: string | null;
+  first_day_of_week?: string | null;
+  time_format?: string | null;
+}
+
+export interface CalendarWorkspaceSettings {
+  timezone?: string | null;
+  first_day_of_week?: string | null;
+}
+
+/**
+ * Detects the system timezone using Intl API
+ */
+export function detectSystemTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    // Fallback to UTC if detection fails
+    return 'UTC';
+  }
+}
+
+/**
+ * Detects the first day of week based on locale
+ * Vietnamese: Monday
+ * US/Canada: Sunday
+ * Middle East: Saturday
+ */
+export function detectLocaleFirstDay(locale?: string): FirstDayOfWeek {
+  const userLocale =
+    locale || (typeof navigator !== 'undefined' ? navigator.language : 'en-US');
+
+  // Vietnamese locale uses Monday as first day
+  if (userLocale.startsWith('vi')) {
+    return 'monday';
+  }
+
+  // US, Canada, and some other countries use Sunday
+  if (userLocale.startsWith('en-US') || userLocale.startsWith('en-CA')) {
+    return 'sunday';
+  }
+
+  // Middle Eastern countries typically use Saturday
+  if (userLocale.startsWith('ar') || userLocale.startsWith('he')) {
+    return 'saturday';
+  }
+
+  // Most European and other countries use Monday
+  return 'monday';
+}
+
+/**
+ * Detects the preferred time format based on locale
+ * Uses Intl.DateTimeFormat to determine if the locale uses 12h or 24h format
+ */
+export function detectLocaleTimeFormat(locale?: string): '12h' | '24h' {
+  const userLocale =
+    locale || (typeof navigator !== 'undefined' ? navigator.language : 'en-US');
+
+  try {
+    // Use Intl.DateTimeFormat to detect the locale's preferred format
+    const formatter = new Intl.DateTimeFormat(userLocale, { hour: 'numeric' });
+    const parts = formatter.formatToParts(new Date(2000, 0, 1, 13, 0));
+    const hourPart = parts.find((p) => p.type === 'hour');
+
+    // If hour is "1" instead of "13", it's 12-hour format
+    return hourPart?.value === '1' ? '12h' : '24h';
+  } catch {
+    // Fallback to 12h for English locales, 24h for others
+    return userLocale.startsWith('en') ? '12h' : '24h';
+  }
+}
+
+/**
+ * Resolves the effective time format based on user setting
+ */
+export function resolveTimeFormat(
+  user?: Pick<CalendarUserSettings, 'time_format'> | null,
+  locale?: string
+): '12h' | '24h' {
+  // User setting takes priority
+  if (user?.time_format && user.time_format !== 'auto') {
+    return user.time_format as '12h' | '24h';
+  }
+
+  // Auto-detection based on locale
+  return detectLocaleTimeFormat(locale);
+}
+
+/**
+ * Resolves the effective timezone based on priority system
+ */
+export function resolveTimezone(
+  user?: Pick<CalendarUserSettings, 'timezone'> | null,
+  workspace?: Pick<CalendarWorkspaceSettings, 'timezone'> | null
+): string {
+  // Priority 1: User setting
+  if (user?.timezone && user.timezone !== 'auto') {
+    return user.timezone;
+  }
+
+  // Priority 2: Workspace setting
+  if (workspace?.timezone && workspace.timezone !== 'auto') {
+    return workspace.timezone;
+  }
+
+  // Priority 3: Auto-detection
+  return detectSystemTimezone();
+}
+
+/**
+ * Resolves the effective first day of week based on priority system
+ */
+export function resolveFirstDayOfWeek(
+  user?: Pick<CalendarUserSettings, 'first_day_of_week'> | null,
+  workspace?: Pick<CalendarWorkspaceSettings, 'first_day_of_week'> | null,
+  locale?: string
+): FirstDayOfWeek {
+  // Priority 1: User setting
+  if (user?.first_day_of_week && user.first_day_of_week !== 'auto') {
+    return user.first_day_of_week as FirstDayOfWeek;
+  }
+
+  // Priority 2: Workspace setting
+  if (workspace?.first_day_of_week && workspace.first_day_of_week !== 'auto') {
+    return workspace.first_day_of_week as FirstDayOfWeek;
+  }
+
+  // Priority 3: Auto-detection based on locale
+  return detectLocaleFirstDay(locale);
+}
+
+/**
+ * Resolves all calendar settings at once
+ */
+export function resolveCalendarSettings(
+  user?: CalendarUserSettings | null,
+  workspace?: CalendarWorkspaceSettings | null,
+  locale?: string
+): CalendarSettings {
+  return {
+    timezone: resolveTimezone(user, workspace),
+    firstDayOfWeek: resolveFirstDayOfWeek(user, workspace, locale),
+    timeFormat: resolveTimeFormat(user, locale),
+  };
+}
+
+/**
+ * Converts first day of week string to number (for Date compatibility)
+ * 0 = Sunday, 1 = Monday, 6 = Saturday
+ */
+export function firstDayToNumber(day: FirstDayOfWeek, locale?: string): number {
+  if (day === 'auto') {
+    day = detectLocaleFirstDay(locale);
+  }
+
+  switch (day) {
+    case 'sunday':
+      return 0;
+    case 'monday':
+      return 1;
+    case 'saturday':
+      return 6;
+    default:
+      return 1; // Default to Monday
+  }
+}
+
+/**
+ * Converts number to first day of week string
+ * 0 = Sunday, 1 = Monday, 6 = Saturday
+ */
+export function numberToFirstDay(num: number): FirstDayOfWeek {
+  switch (num) {
+    case 0:
+      return 'sunday';
+    case 1:
+      return 'monday';
+    case 6:
+      return 'saturday';
+    default:
+      return 'monday'; // Default to Monday
+  }
+}

package/src/internal-domains.ts

@@ -16,6 +16,10 @@ export const PRODUCTION_INTERNAL_APP_DOMAINS = [
     name: 'cms',
     url: 'https://cms.tuturuuu.com',
   },
+  {
+    name: 'docs',
+    url: 'https://docs.tuturuuu.com',
+  },
   {
     name: 'calendar',
     url: 'https://calendar.tuturuuu.com',
@@ -96,6 +100,14 @@ export const PRODUCTION_INTERNAL_APP_DOMAINS = [
     name: 'teach',
     url: 'https://teach.tuturuuu.com',
   },
+  {
+    name: 'pay',
+    url: 'https://pay.tuturuuu.com',
+  },
+  {
+    name: 'contacts',
+    url: 'https://contacts.tuturuuu.com',
+  },
   {
     name: 'hive',
     url: 'https://hive.tuturuuu.com',
@@ -119,6 +131,10 @@ export const PORTLESS_INTERNAL_APP_DOMAINS = [
     name: 'cms',
     url: getTuturuuuPortlessAppOrigin('cms'),
   },
+  {
+    name: 'docs',
+    url: getTuturuuuPortlessAppOrigin('docs'),
+  },
   {
     name: 'calendar',
     url: getTuturuuuPortlessAppOrigin('calendar'),
@@ -191,6 +207,14 @@ export const PORTLESS_INTERNAL_APP_DOMAINS = [
     name: 'teach',
     url: getTuturuuuPortlessAppOrigin('teach'),
   },
+  {
+    name: 'pay',
+    url: getTuturuuuPortlessAppOrigin('pay'),
+  },
+  {
+    name: 'contacts',
+    url: getTuturuuuPortlessAppOrigin('contacts'),
+  },
   {
     name: 'hive',
     url: getTuturuuuPortlessAppOrigin('hive'),
@@ -286,6 +310,14 @@ export const LOCALHOST_INTERNAL_APP_DOMAINS = [
     name: 'teach',
     url: 'http://localhost:7813',
   },
+  {
+    name: 'pay',
+    url: 'http://localhost:7826',
+  },
+  {
+    name: 'contacts',
+    url: 'http://localhost:7827',
+  },
   {
     name: 'hive',
     url: 'http://localhost:7814',

package/src/launchable-apps.test.ts

@@ -3,6 +3,8 @@ import {
   getLaunchableApp,
   getLaunchableAppByTitle,
   getLaunchableAppOrigin,
+  LAUNCHABLE_APP_CATEGORIES,
+  LAUNCHABLE_APPS,
   type LaunchableWorkspace,
   resolveLaunchableAppPath,
   resolveLaunchableAppUrl,
@@ -27,6 +29,39 @@ describe('launchable apps', () => {
     expect(getLaunchableAppByTitle('apps gateway')?.slug).toBe('apps');
   });
 
+  it('keeps retired apps out of the catalog and pins category overrides', () => {
+    expect(LAUNCHABLE_APPS.map((app) => app.slug)).not.toContain('external');
+    expect(LAUNCHABLE_APPS.map((app) => app.slug)).not.toContain('playground');
+    expect(LAUNCHABLE_APP_CATEGORIES).not.toContain('core');
+    expect(LAUNCHABLE_APP_CATEGORIES).not.toContain('content');
+    expect(LAUNCHABLE_APP_CATEGORIES).not.toContain('developer');
+    expect(LAUNCHABLE_APP_CATEGORIES).toContain('miscellaneous');
+    expect(getLaunchableApp('external')).toBeNull();
+    expect(getLaunchableApp('playground')).toBeNull();
+    expect(getLaunchableApp('platform')?.category).toBe('productivity');
+    expect(getLaunchableApp('apps')?.category).toBe('miscellaneous');
+    expect(getLaunchableApp('cms')?.category).toBe('operations');
+    expect(getLaunchableApp('rewise')?.category).toBe('ai');
+    expect(getLaunchableApp('docs')?.category).toBe('miscellaneous');
+    expect(getLaunchableApp('tools')?.category).toBe('miscellaneous');
+    expect(getLaunchableApp('shortener')?.category).toBe('miscellaneous');
+    expect(
+      LAUNCHABLE_APPS.filter((app) => app.category === 'productivity').map(
+        (app) => app.slug
+      )[0]
+    ).toBe('platform');
+    expect(
+      LAUNCHABLE_APPS.filter((app) => app.category === 'operations').map(
+        (app) => app.slug
+      )
+    ).not.toContain('apps');
+    expect(
+      LAUNCHABLE_APPS.filter((app) => app.category === 'miscellaneous').map(
+        (app) => app.slug
+      )[0]
+    ).toBe('apps');
+  });
+
   it('resolves production, Portless, and local origins', () => {
     const app = getLaunchableApp('calendar');
 
@@ -46,6 +81,15 @@ describe('launchable apps', () => {
     expect(getLaunchableAppOrigin(meet!, { environment: 'production' })).toBe(
       'https://meet.tuturuuu.com'
     );
+
+    const docs = getLaunchableApp('docs');
+    expect(docs).not.toBeNull();
+    expect(getLaunchableAppOrigin(docs!, { environment: 'production' })).toBe(
+      'https://docs.tuturuuu.com'
+    );
+    expect(getLaunchableAppOrigin(docs!, { environment: 'portless' })).toBe(
+      'https://docs.tuturuuu.localhost'
+    );
   });
 
   it('detects Portless dev from the current origin', () => {

package/src/launchable-apps.ts

@@ -2,13 +2,11 @@ import { toWorkspaceSlug } from './constants';
 import { getTuturuuuPortlessAppOrigin } from './portless';
 
 export const LAUNCHABLE_APP_CATEGORIES = [
-  'core',
   'productivity',
-  'content',
   'operations',
   'learning',
-  'developer',
   'ai',
+  'miscellaneous',
 ] as const;
 
 export type LaunchableAppCategory = (typeof LAUNCHABLE_APP_CATEGORIES)[number];
@@ -53,7 +51,7 @@ export const LAUNCHABLE_APPS = [
   {
     aliases: ['Tuturuuu', 'Dashboard', 'Workspace'],
     appRoot: 'apps/web',
-    category: 'core',
+    category: 'productivity',
     defaultPath: '/',
     localhostOrigin: 'http://localhost:7803',
     packageName: '@tuturuuu/web',
@@ -63,18 +61,6 @@ export const LAUNCHABLE_APPS = [
     title: 'Platform',
     workspacePathResolver: workspaceRootPath,
   },
-  {
-    aliases: ['App Launcher', 'Gateway', 'Apps Gateway'],
-    appRoot: 'apps/apps',
-    category: 'core',
-    defaultPath: '/',
-    localhostOrigin: 'http://localhost:7818',
-    packageName: '@tuturuuu/apps',
-    portlessApp: 'apps',
-    productionUrl: 'https://apps.tuturuuu.com',
-    slug: 'apps',
-    title: 'Apps',
-  },
   {
     aliases: ['Schedule', 'Events'],
     appRoot: 'apps/calendar',
@@ -104,7 +90,7 @@ export const LAUNCHABLE_APPS = [
   {
     aliases: ['Content', 'CMS'],
     appRoot: 'apps/cms',
-    category: 'content',
+    category: 'operations',
     defaultPath: '/personal',
     localhostOrigin: 'http://localhost:7811',
     packageName: '@tuturuuu/cms',
@@ -128,15 +114,27 @@ export const LAUNCHABLE_APPS = [
     workspacePathResolver: workspaceRootPath,
   },
   {
-    aliases: ['External Projects', 'WebGL'],
-    appRoot: 'apps/external',
-    category: 'developer',
+    aliases: ['App Launcher', 'Gateway', 'Apps Gateway'],
+    appRoot: 'apps/apps',
+    category: 'miscellaneous',
     defaultPath: '/',
-    packageName: '@tuturuuu/external',
-    portlessApp: 'external',
-    productionUrl: 'https://external.tuturuuu.com',
-    slug: 'external',
-    title: 'External',
+    localhostOrigin: 'http://localhost:7818',
+    packageName: '@tuturuuu/apps',
+    portlessApp: 'apps',
+    productionUrl: 'https://apps.tuturuuu.com',
+    slug: 'apps',
+    title: 'Apps',
+  },
+  {
+    aliases: ['Documentation', 'Guides', 'Reference'],
+    appRoot: 'apps/docs',
+    category: 'miscellaneous',
+    defaultPath: '/',
+    packageName: 'apps/docs',
+    portlessApp: 'docs',
+    productionUrl: 'https://docs.tuturuuu.com',
+    slug: 'docs',
+    title: 'Docs',
   },
   {
     aliases: ['Money', 'Wallets', 'Invoices'],
@@ -251,21 +249,10 @@ export const LAUNCHABLE_APPS = [
     slug: 'nova',
     title: 'Nova',
   },
-  {
-    aliases: ['Labs', 'Sandbox'],
-    appRoot: 'apps/playground',
-    category: 'developer',
-    defaultPath: '/',
-    packageName: '@tuturuuu/playground',
-    portlessApp: 'playground',
-    productionUrl: 'https://playground.tuturuuu.com',
-    slug: 'playground',
-    title: 'Playground',
-  },
   {
     aliases: ['QR Code', 'Generator', 'Password', 'Random', 'UUID', 'Token'],
     appRoot: 'apps/tools',
-    category: 'developer',
+    category: 'miscellaneous',
     defaultPath: '/',
     localhostOrigin: 'http://localhost:7825',
     packageName: '@tuturuuu/tools',
@@ -277,7 +264,7 @@ export const LAUNCHABLE_APPS = [
   {
     aliases: ['Review', 'Flashcards'],
     appRoot: 'apps/rewise',
-    category: 'learning',
+    category: 'ai',
     defaultPath: '/',
     localhostOrigin: 'http://localhost:7804',
     packageName: '@tuturuuu/rewise',
@@ -289,7 +276,7 @@ export const LAUNCHABLE_APPS = [
   {
     aliases: ['Links', 'URL Shortener'],
     appRoot: 'apps/shortener',
-    category: 'developer',
+    category: 'miscellaneous',
     defaultPath: '/',
     packageName: '@tuturuuu/shortener',
     portlessApp: 'shortener',
@@ -323,6 +310,32 @@ export const LAUNCHABLE_APPS = [
     title: 'Teach',
     workspacePathResolver: workspaceRootPath,
   },
+  {
+    aliases: ['Billing', 'Subscriptions', 'Payments'],
+    appRoot: 'apps/pay',
+    category: 'operations',
+    defaultPath: '/personal',
+    localhostOrigin: 'http://localhost:7826',
+    packageName: '@tuturuuu/pay',
+    portlessApp: 'pay',
+    productionUrl: 'https://pay.tuturuuu.com',
+    slug: 'pay',
+    title: 'Pay',
+    workspacePathResolver: workspaceRootPath,
+  },
+  {
+    aliases: ['CRM', 'Users', 'Members', 'Customers', 'Leads'],
+    appRoot: 'apps/contacts',
+    category: 'operations',
+    defaultPath: '/personal',
+    localhostOrigin: 'http://localhost:7827',
+    packageName: '@tuturuuu/contacts',
+    portlessApp: 'contacts',
+    productionUrl: 'https://contacts.tuturuuu.com',
+    slug: 'contacts',
+    title: 'Contacts',
+    workspacePathResolver: workspaceRootPath,
+  },
   {
     aliases: ['Time Tracking', 'Timer'],
     appRoot: 'apps/track',

package/src/platform-release.test.ts

@@ -7,10 +7,10 @@ import {
 
 describe('platform release metadata', () => {
   it('uses the centralized shared browser app version', () => {
-    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.18.0'); // x-release-please-version
+    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.21.0'); // x-release-please-version
   });
 
-  it('normalizes generated metadata and derives a short hash', () => {
+  it('preserves the source timestamp in builtAt and derives a short hash', () => {
     expect(
       normalizePlatformBuildMetadata({
         builtAt: '2026-05-27T10:00:00.000Z',

package/src/platform-release.ts

@@ -1,8 +1,9 @@
 import { PLATFORM_BUILD_METADATA } from './generated/platform-build-metadata';
 
-export const TUTURUUU_PLATFORM_VERSION = '0.18.0'; // x-release-please-version
+export const TUTURUUU_PLATFORM_VERSION = '0.21.0'; // x-release-please-version
 
 export type PlatformBuildMetadataInput = {
+  /** ISO timestamp of the source commit used for the build, not deployment time. */
   builtAt?: string | null;
   commitHash?: string | null;
   commitMessage?: string | null;
@@ -14,6 +15,7 @@ export type PlatformBuildMetadataInput = {
 };
 
 export type PlatformBuildMetadata = {
+  /** ISO timestamp of the source commit used for the build, not deployment time. */
   builtAt: string;
   commitHash: string;
   commitMessage: string;

package/src/portless.ts

@@ -10,6 +10,8 @@ export const TUTURUUU_PORTLESS_APP_ORIGINS = {
   calendar: `https://calendar.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   chat: `https://chat.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   cms: `https://cms.${TUTURUUU_PORTLESS_ROOT_HOST}`,
+  contacts: `https://contacts.${TUTURUUU_PORTLESS_ROOT_HOST}`,
+  docs: `https://docs.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   drive: `https://drive.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   external: `https://external.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   finance: `https://finance.${TUTURUUU_PORTLESS_ROOT_HOST}`,
@@ -22,6 +24,7 @@ export const TUTURUUU_PORTLESS_APP_ORIGINS = {
   meet: `https://meet.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   mind: `https://mind.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   nova: `https://nova.${TUTURUUU_PORTLESS_ROOT_HOST}`,
+  pay: `https://pay.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   platform: TUTURUUU_PORTLESS_ROOT_ORIGIN,
   playground: `https://playground.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   qr: `https://qr.${TUTURUUU_PORTLESS_ROOT_HOST}`,

package/src/shared-cookie.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getHostOnlyCookieOptions,
+  getSharedAndHostOnlyCookieDeleteOptions,
+  getTuturuuuSharedCookieOptions,
+  resolveTuturuuuSharedCookieDomain,
+} from './shared-cookie';
+
+describe('shared Tuturuuu cookie helpers', () => {
+  it('resolves production root and subdomains to the parent domain', () => {
+    expect(
+      resolveTuturuuuSharedCookieDomain('https://tuturuuu.com')?.cookieDomain
+    ).toBe('.tuturuuu.com');
+    expect(
+      resolveTuturuuuSharedCookieDomain('https://tasks.tuturuuu.com')
+    ).toMatchObject({
+      cookieDomain: '.tuturuuu.com',
+      secure: true,
+    });
+  });
+
+  it('resolves local first-party subdomains without Secure cookies', () => {
+    expect(
+      resolveTuturuuuSharedCookieDomain('https://tasks.tuturuuu.localhost')
+    ).toMatchObject({
+      cookieDomain: '.tuturuuu.localhost',
+      secure: false,
+    });
+  });
+
+  it('uses forwarded host headers for server requests', () => {
+    const request = new Request('http://internal.localhost/api', {
+      headers: {
+        'x-forwarded-host': 'calendar.tuturuuu.com',
+        'x-forwarded-proto': 'https',
+      },
+    });
+
+    expect(resolveTuturuuuSharedCookieDomain(request)).toMatchObject({
+      cookieDomain: '.tuturuuu.com',
+      secure: true,
+    });
+  });
+
+  it('does not share cookies on preview, localhost, or custom domains', () => {
+    expect(
+      resolveTuturuuuSharedCookieDomain('https://tuturuuu-git-main.vercel.app')
+    ).toBe(null);
+    expect(resolveTuturuuuSharedCookieDomain('http://localhost:7803')).toBe(
+      null
+    );
+    expect(resolveTuturuuuSharedCookieDomain('https://nova.ai.vn')).toBe(null);
+  });
+
+  it('applies shared options only when the current host is first-party', () => {
+    expect(
+      getTuturuuuSharedCookieOptions(
+        { maxAge: 60, path: '/', sameSite: 'lax' as const },
+        'https://finance.tuturuuu.com'
+      )
+    ).toEqual({
+      domain: '.tuturuuu.com',
+      maxAge: 60,
+      path: '/',
+      sameSite: 'lax',
+      secure: true,
+    });
+    expect(
+      getTuturuuuSharedCookieOptions(
+        { maxAge: 60, path: '/', sameSite: 'lax' as const },
+        'https://rewise.me'
+      )
+    ).toEqual({
+      maxAge: 60,
+      path: '/',
+      sameSite: 'lax',
+    });
+  });
+
+  it('returns host-only and shared delete options when a shared domain exists', () => {
+    expect(
+      getSharedAndHostOnlyCookieDeleteOptions(
+        { path: '/', sameSite: 'lax' as const },
+        'https://drive.tuturuuu.com'
+      )
+    ).toEqual([
+      {
+        maxAge: 0,
+        path: '/',
+        sameSite: 'lax',
+      },
+      {
+        domain: '.tuturuuu.com',
+        maxAge: 0,
+        path: '/',
+        sameSite: 'lax',
+        secure: true,
+      },
+    ]);
+  });
+
+  it('strips domains from host-only options', () => {
+    expect(
+      getHostOnlyCookieOptions({
+        domain: '.tuturuuu.com',
+        maxAge: 0,
+        path: '/',
+      })
+    ).toEqual({
+      maxAge: 0,
+      path: '/',
+    });
+  });
+});

package/src/shared-cookie.ts

@@ -0,0 +1,235 @@
+export interface TuturuuuSharedCookieDomain {
+  cookieDomain: '.tuturuuu.com' | '.tuturuuu.localhost';
+  hostname: 'tuturuuu.com' | 'tuturuuu.localhost';
+  secure: boolean;
+}
+
+export type CookieOptionsLike = {
+  domain?: string;
+  expires?: Date;
+  maxAge?: number;
+  path?: string;
+  sameSite?: boolean | 'lax' | 'none' | 'strict';
+  secure?: boolean;
+};
+
+type HeaderReader =
+  | Headers
+  | Pick<Headers, 'get'>
+  | Record<string, string | null | undefined>;
+
+type CookieSource =
+  | URL
+  | string
+  | {
+      headers?: HeaderReader;
+      url?: string;
+    }
+  | null
+  | undefined;
+
+export const TUTURUUU_SHARED_COOKIE_DOMAINS = [
+  {
+    cookieDomain: '.tuturuuu.com',
+    hostname: 'tuturuuu.com',
+    secure: true,
+  },
+  {
+    cookieDomain: '.tuturuuu.localhost',
+    hostname: 'tuturuuu.localhost',
+    secure: false,
+  },
+] as const satisfies readonly TuturuuuSharedCookieDomain[];
+
+const ENV_APP_URL_KEYS = [
+  'PORTLESS_URL',
+  'NEXT_PUBLIC_APP_URL',
+  'NEXT_PUBLIC_WEB_APP_URL',
+  'WEB_APP_URL',
+  'VERCEL_URL',
+] as const;
+
+function normalizeUrlLike(value: string | URL | null | undefined) {
+  if (!value) return null;
+
+  if (value instanceof URL) return value;
+
+  try {
+    return new URL(value);
+  } catch {
+    try {
+      return new URL(`https://${value}`);
+    } catch {
+      return null;
+    }
+  }
+}
+
+function readHeader(headers: HeaderReader | undefined, name: string) {
+  if (!headers) return null;
+
+  if ('get' in headers && typeof headers.get === 'function') {
+    return headers.get(name);
+  }
+
+  const lowerName = name.toLowerCase();
+  const record = headers as Record<string, string | null | undefined>;
+
+  return record[name] ?? record[lowerName] ?? null;
+}
+
+function extractForwardedValue(value: string | null | undefined) {
+  return value
+    ?.split(',')
+    .map((entry) => entry.trim())
+    .find(Boolean);
+}
+
+function configuredAppUrl() {
+  if (typeof window !== 'undefined' && window.location?.href) {
+    return window.location.href;
+  }
+
+  for (const key of ENV_APP_URL_KEYS) {
+    const value = process.env[key];
+    if (value) return value;
+  }
+
+  return null;
+}
+
+function resolveUrlFromRequestLike(
+  source: Extract<CookieSource, { headers?: HeaderReader; url?: string }>
+) {
+  const forwardedHost =
+    extractForwardedValue(readHeader(source.headers, 'x-forwarded-host')) ??
+    extractForwardedValue(readHeader(source.headers, 'host'));
+
+  if (forwardedHost && !/[\r\n]/u.test(forwardedHost)) {
+    const forwardedProto = extractForwardedValue(
+      readHeader(source.headers, 'x-forwarded-proto')
+    );
+    const fallbackProtocol = normalizeUrlLike(source.url)?.protocol ?? 'https:';
+    const protocol =
+      forwardedProto?.replace(/:$/u, '') === 'http'
+        ? 'http:'
+        : fallbackProtocol === 'http:'
+          ? 'http:'
+          : 'https:';
+
+    return normalizeUrlLike(`${protocol}//${forwardedHost}`);
+  }
+
+  return normalizeUrlLike(source.url);
+}
+
+function resolveCookieUrl(source: CookieSource) {
+  if (!source) {
+    return normalizeUrlLike(configuredAppUrl());
+  }
+
+  if (typeof source === 'string' || source instanceof URL) {
+    return normalizeUrlLike(source);
+  }
+
+  return resolveUrlFromRequestLike(source);
+}
+
+function domainForUrl(url: string | URL | null | undefined) {
+  const parsedUrl = normalizeUrlLike(url);
+  const hostname = parsedUrl?.hostname.toLowerCase();
+
+  if (!hostname) return null;
+
+  return (
+    TUTURUUU_SHARED_COOKIE_DOMAINS.find(
+      (entry) =>
+        hostname === entry.hostname || hostname.endsWith(`.${entry.hostname}`)
+    ) ?? null
+  );
+}
+
+function isPortlessBackendUrl(sourceUrl: URL | null) {
+  const portlessUrl = normalizeUrlLike(process.env.PORTLESS_URL);
+  const expectedPort = process.env.PORT;
+
+  if (!sourceUrl || !portlessUrl || !expectedPort) return false;
+  if (!domainForUrl(portlessUrl)) return false;
+
+  return (
+    (sourceUrl.protocol === 'http:' || sourceUrl.protocol === 'https:') &&
+    (sourceUrl.hostname === '127.0.0.1' ||
+      sourceUrl.hostname === 'localhost') &&
+    sourceUrl.port === expectedPort
+  );
+}
+
+export function resolveTuturuuuSharedCookieDomain(source?: CookieSource) {
+  const sourceUrl = resolveCookieUrl(source);
+  const sourceDomain = domainForUrl(sourceUrl);
+
+  if (sourceDomain) return sourceDomain;
+
+  if (isPortlessBackendUrl(sourceUrl)) {
+    return domainForUrl(process.env.PORTLESS_URL);
+  }
+
+  return null;
+}
+
+export function getTuturuuuSharedCookieOptions<
+  TOptions extends CookieOptionsLike,
+>(options: TOptions, source?: CookieSource): TOptions {
+  const sharedDomain = resolveTuturuuuSharedCookieDomain(source);
+  const nextOptions = {
+    ...options,
+    path: options.path ?? '/',
+  };
+
+  if (!sharedDomain) return nextOptions;
+
+  return {
+    ...nextOptions,
+    domain: sharedDomain.cookieDomain,
+    secure: sharedDomain.secure,
+  };
+}
+
+export function getTuturuuuBrowserSharedCookieOptions<
+  TOptions extends CookieOptionsLike,
+>(options: TOptions): TOptions {
+  return getTuturuuuSharedCookieOptions(options);
+}
+
+export function getHostOnlyCookieOptions<TOptions extends CookieOptionsLike>(
+  options: TOptions
+): TOptions {
+  const { domain: _domain, ...hostOnlyOptions } = options;
+
+  return {
+    ...hostOnlyOptions,
+    path: options.path ?? '/',
+  } as TOptions;
+}
+
+export function getSharedAndHostOnlyCookieDeleteOptions<
+  TOptions extends CookieOptionsLike,
+>(options: TOptions, source?: CookieSource): TOptions[] {
+  const hostOnlyOptions = getHostOnlyCookieOptions({
+    ...options,
+    maxAge: 0,
+    path: options.path ?? '/',
+  });
+  const sharedOptions = getTuturuuuSharedCookieOptions(
+    {
+      ...options,
+      maxAge: 0,
+      path: options.path ?? '/',
+    },
+    source
+  );
+
+  if (!sharedOptions.domain) return [hostOnlyOptions];
+
+  return [hostOnlyOptions, sharedOptions];
+}

package/src/topic-announcements.ts

@@ -0,0 +1 @@
+export const TOPIC_ANNOUNCEMENTS_SECRET = 'ENABLE_TOPIC_ANNOUNCEMENTS';

package/src/user-helper.ts

@@ -1,13 +1,8 @@
 import type { TypedSupabaseClient } from '@tuturuuu/supabase/next/client';
-import {
-  createAdminClient,
-  createClient,
-} from '@tuturuuu/supabase/next/server';
+import { createClient } from '@tuturuuu/supabase/next/server';
 import type { User, UserPrivateDetails } from '@tuturuuu/types';
 import type { WorkspaceUser } from '@tuturuuu/types/primitives/WorkspaceUser';
-
-import { resolveWorkspaceId } from './constants';
-import { verifyWorkspaceMembershipType } from './workspace-helper';
+import { getWorkspaceUserLinkForUser } from './workspace-user-link';
 
 async function resolveCurrentUserId(
   supabase: TypedSupabaseClient
@@ -71,98 +66,14 @@ export async function getCurrentWorkspaceUser(
   wsId: string,
   options: GetCurrentWorkspaceUserOptions = {}
 ): Promise<WorkspaceUserLink | null> {
-  const { autoRepair = true } = options;
-
   const supabase = await createClient();
   const userId = await resolveCurrentUserId(supabase as TypedSupabaseClient);
   if (!userId) return null;
 
-  const resolvedWsId = resolveWorkspaceId(wsId);
-
-  // First attempt to get the workspace user link
-  const { data: workspaceUser } = await supabase
-    .from('workspace_user_linked_users')
-    .select(
-      'platform_user_id, virtual_user_id, ws_id, created_at, workspace_users!virtual_user_id(*)'
-    )
-    .eq('platform_user_id', userId)
-    .eq('ws_id', resolvedWsId)
-    .limit(1)
-    .maybeSingle();
-
-  // If found, return it
-  if (workspaceUser) {
-    const linkedData = workspaceUser.workspace_users;
-    return {
-      platform_user_id: workspaceUser.platform_user_id,
-      virtual_user_id: workspaceUser.virtual_user_id,
-      ws_id: workspaceUser.ws_id,
-      created_at: workspaceUser.created_at,
-      ...(linkedData ? { workspace_users: linkedData as WorkspaceUser } : {}),
-    };
-  }
-
-  // If not found and auto-repair is disabled, return null
-  if (!autoRepair) return null;
-
-  const membership = await verifyWorkspaceMembershipType({
-    wsId: resolvedWsId,
-    userId,
-    supabase,
-    requiredType: 'MEMBER',
-  });
-
-  if (!membership.ok) return null;
-
-  // Try to repair the missing link using the RPC function
-  try {
-    const sbAdmin = await createAdminClient();
-    // Note: ensure_workspace_user_link is defined in migration 20260112060000
-    // Using type assertion since RPC types are generated after migration is applied
-    // IMPORTANT: Must use .bind() to preserve the Supabase client's `this` context
-    const rpc = sbAdmin.rpc.bind(sbAdmin) as unknown as (
-      fn: string,
-      args: Record<string, unknown>
-    ) => Promise<{ error: Error | null }>;
-    const { error: repairError } = await rpc('ensure_workspace_user_link', {
-      target_user_id: userId,
-      target_ws_id: resolvedWsId,
-    });
-
-    if (repairError) {
-      console.error(
-        '[getCurrentWorkspaceUser] Failed to auto-repair workspace user link:',
-        repairError
-      );
-      return null;
-    }
-
-    // Fetch the newly created link
-    const { data: repairedUser } = await supabase
-      .from('workspace_user_linked_users')
-      .select(
-        'platform_user_id, virtual_user_id, ws_id, created_at, workspace_users!virtual_user_id(*)'
-      )
-      .eq('platform_user_id', userId)
-      .eq('ws_id', resolvedWsId)
-      .limit(1)
-      .maybeSingle();
-
-    if (repairedUser) {
-      const linkedData = repairedUser.workspace_users;
-      return {
-        platform_user_id: repairedUser.platform_user_id,
-        virtual_user_id: repairedUser.virtual_user_id,
-        ws_id: repairedUser.ws_id,
-        created_at: repairedUser.created_at,
-        ...(linkedData ? { workspace_users: linkedData as WorkspaceUser } : {}),
-      };
-    }
-  } catch (err) {
-    console.error('[getCurrentWorkspaceUser] Error during auto-repair:', err);
-  }
-
-  return null;
+  // The link lookup + auto-repair lives in workspace-user-link so satellite apps
+  // can reuse it with an app-session actor: the internal-app-auth guard forbids
+  // registered apps from importing this module (it resolves actors via Supabase).
+  return getWorkspaceUserLinkForUser(wsId, userId, options);
 }
 
 export async function getCurrentUser() {

package/src/workspace-user-link.test.ts

@@ -0,0 +1,53 @@
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  createAdminClient: vi.fn(),
+  createClient: vi.fn(),
+  verifyWorkspaceMembershipType: vi.fn(),
+}));
+
+vi.mock('@tuturuuu/supabase/next/server', () => ({
+  createAdminClient: mocks.createAdminClient,
+  createClient: mocks.createClient,
+}));
+vi.mock('./workspace-helper', () => ({
+  verifyWorkspaceMembershipType: mocks.verifyWorkspaceMembershipType,
+}));
+
+import { getWorkspaceUserLinkForUser } from './workspace-user-link';
+
+describe('getWorkspaceUserLinkForUser', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('uses an injected authorization client for satellite actors', async () => {
+    const link = {
+      created_at: '2026-07-13T00:00:00.000Z',
+      platform_user_id: 'platform-user-1',
+      virtual_user_id: 'virtual-user-1',
+      ws_id: 'workspace-1',
+    };
+    const maybeSingle = vi.fn().mockResolvedValue({ data: link, error: null });
+    const limit = vi.fn(() => ({ maybeSingle }));
+    const secondEq = vi.fn(() => ({ limit }));
+    const firstEq = vi.fn(() => ({ eq: secondEq }));
+    const select = vi.fn(() => ({ eq: firstEq }));
+    const authorizationClient = {
+      from: vi.fn(() => ({ select })),
+    } as unknown as TypedSupabaseClient;
+
+    await expect(
+      getWorkspaceUserLinkForUser('workspace-1', 'platform-user-1', {
+        authorizationClient,
+      })
+    ).resolves.toEqual(link);
+
+    expect(authorizationClient.from).toHaveBeenCalledWith(
+      'workspace_user_linked_users'
+    );
+    expect(mocks.createClient).not.toHaveBeenCalled();
+    expect(mocks.createAdminClient).not.toHaveBeenCalled();
+  });
+});

package/src/workspace-user-link.ts

@@ -0,0 +1,122 @@
+import {
+  createAdminClient,
+  createClient,
+} from '@tuturuuu/supabase/next/server';
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import type { WorkspaceUser } from '@tuturuuu/types/primitives/WorkspaceUser';
+import { resolveWorkspaceId } from './constants';
+import { verifyWorkspaceMembershipType } from './workspace-helper';
+
+export interface WorkspaceUserLink {
+  platform_user_id: string;
+  virtual_user_id: string;
+  ws_id: string;
+  created_at: string;
+  workspace_users?: WorkspaceUser;
+}
+
+const LINK_SELECT =
+  'platform_user_id, virtual_user_id, ws_id, created_at, workspace_users!virtual_user_id(*)';
+
+type LinkRow = {
+  platform_user_id: string;
+  virtual_user_id: string;
+  ws_id: string;
+  created_at: string;
+  workspace_users?: unknown;
+};
+
+function toLink(row: LinkRow): WorkspaceUserLink {
+  const linkedData = row.workspace_users;
+  return {
+    platform_user_id: row.platform_user_id,
+    virtual_user_id: row.virtual_user_id,
+    ws_id: row.ws_id,
+    created_at: row.created_at,
+    ...(linkedData ? { workspace_users: linkedData as WorkspaceUser } : {}),
+  };
+}
+
+/**
+ * Resolves the workspace-user link for an EXPLICIT platform user id.
+ *
+ * `getCurrentWorkspaceUser` (user-helper) resolves the actor from Supabase auth
+ * and then delegates here. Satellite apps must not do that: they resolve the
+ * actor from Tuturuuu app-session auth (`getSatelliteAppSessionUser`) and pass
+ * the id in, which is why this lives outside `user-helper` — the internal-app-auth
+ * guard forbids registered apps from importing that module.
+ */
+export async function getWorkspaceUserLinkForUser(
+  wsId: string,
+  userId: string,
+  options: {
+    authorizationClient?: TypedSupabaseClient;
+    autoRepair?: boolean;
+  } = {}
+): Promise<WorkspaceUserLink | null> {
+  const { authorizationClient, autoRepair = true } = options;
+  if (!userId) return null;
+
+  const supabase = authorizationClient ?? (await createClient());
+  const resolvedWsId = resolveWorkspaceId(wsId);
+
+  const { data: workspaceUser } = await supabase
+    .from('workspace_user_linked_users')
+    .select(LINK_SELECT)
+    .eq('platform_user_id', userId)
+    .eq('ws_id', resolvedWsId)
+    .limit(1)
+    .maybeSingle();
+
+  if (workspaceUser) return toLink(workspaceUser as LinkRow);
+
+  if (!autoRepair) return null;
+
+  const membership = await verifyWorkspaceMembershipType({
+    wsId: resolvedWsId,
+    userId,
+    supabase,
+    requiredType: 'MEMBER',
+  });
+
+  if (!membership.ok) return null;
+
+  try {
+    const sbAdmin = await createAdminClient();
+    // Note: ensure_workspace_user_link is defined in migration 20260112060000.
+    // IMPORTANT: must use .bind() to preserve the Supabase client's `this` context.
+    const rpc = sbAdmin.rpc.bind(sbAdmin) as unknown as (
+      fn: string,
+      args: Record<string, unknown>
+    ) => Promise<{ error: Error | null }>;
+    const { error: repairError } = await rpc('ensure_workspace_user_link', {
+      target_user_id: userId,
+      target_ws_id: resolvedWsId,
+    });
+
+    if (repairError) {
+      console.error(
+        '[getWorkspaceUserLinkForUser] Failed to auto-repair workspace user link:',
+        repairError
+      );
+      return null;
+    }
+
+    const { data: repairedUser } = await supabase
+      .from('workspace_user_linked_users')
+      .select(LINK_SELECT)
+      .eq('platform_user_id', userId)
+      .eq('ws_id', resolvedWsId)
+      .limit(1)
+      .maybeSingle();
+
+    if (repairedUser) return toLink(repairedUser as LinkRow);
+  } catch (err) {
+    console.error(
+      '[getWorkspaceUserLinkForUser] Error during auto-repair:',
+      err
+    );
+  }
+
+  return null;
+}

package/src/yjs-helper.ts

@@ -1,5 +1,5 @@
 import type { JSONContent } from '@tiptap/react';
-import { Node as ProseMirrorNode, type Schema } from 'prosemirror-model';
+import type { Schema } from 'prosemirror-model';
 import * as Y from 'yjs';
 
 const PROSEMIRROR_FRAGMENT_NAME = 'prosemirror';
@@ -179,7 +179,7 @@ function validateJsonContent(
     return jsonContent;
   }
 
-  return ProseMirrorNode.fromJSON(schema, jsonContent).toJSON() as JSONContent;
+  return schema.nodeFromJSON(jsonContent).toJSON() as JSONContent;
 }
 
 export function convertJsonContentToYjsState(