@robono/server 0.21.0 → 0.22.0

package/legacy/0.21.0/messenger-customer-templates.js

@@ -0,0 +1,111 @@
+/** A single customer-facing component; account wiring and diagnostics stay generated. */
+export function customerMessengerTemplates(options) {
+    const provider = options.auth ?? 'custom';
+    const web = options.platform === 'web';
+    const type = provider === 'supabase' ? 'SupabaseClient' : provider === 'firebase' ? 'Auth' : 'RobonoAccounts';
+    const typeImport = provider === 'supabase' ? "import type {SupabaseClient} from '@supabase/supabase-js';" : provider === 'firebase' ? "import type {Auth} from 'firebase/auth';" : "import type {RobonoAccounts} from './ConnectedRobonoChat';";
+    return {
+        'client/CustomerMessenger.tsx': `'use client';
+import React,{useMemo,type ComponentProps} from 'react';
+import {ConnectedRobonoChat} from './ConnectedRobonoChat';
+import {MessengerSetup} from './MessengerSetup';
+${typeImport}
+${provider === 'custom' ? '' : "import {robonoAccounts} from './robono-accounts';"}
+type Props=Omit<ComponentProps<typeof ConnectedRobonoChat>,'accounts'>&{
+  ${provider === 'custom' ? 'accounts' : 'auth'}:${type};
+  /** Optional development-only connection check. Never shown in a production build. */
+  setupChecks?:boolean;
+};
+export function CustomerMessenger({${provider === 'custom' ? 'accounts' : 'auth'},setupChecks=false,...props}:Props){
+  ${provider === 'custom' ? '' : 'const accounts=useMemo(()=>robonoAccounts(auth),[auth]);'}
+  return <>
+    {setupChecks&&${web ? "process.env.NODE_ENV==='development'" : '__DEV__'}&&<MessengerSetup accounts={accounts}/>}
+    <ConnectedRobonoChat accounts={accounts} {...props}/>
+  </>;
+}
+`,
+        'client/check-messenger-connection.ts': `export interface ConnectionCheck {name:string;status:'passed'|'failed'|'needs-action';detail:string}
+/** Read-only checks in the signed-in app. Tokens never enter the report or Robono's website. */
+export async function checkMessengerConnection(getAccessToken:()=>Promise<string>,signal:AbortSignal):Promise<ConnectionCheck[]>{
+  const endpoint=${JSON.stringify(web ? '/api/robono' : options.origin + '/api/robono')};
+  const checks:ConnectionCheck[]=[];
+  const run=async(name:string,operation:string,service:string,inspect:(data:any)=>Omit<ConnectionCheck,'name'>)=>{
+    try{
+      const token=await getAccessToken();
+      if(signal.aborted)throw Error('Cancelled');
+      const response=await fetch(endpoint+'?service='+service,{method:'POST',redirect:'error',signal,
+        headers:{'content-type':'application/json',authorization:'Bearer '+token},body:JSON.stringify({operation})});
+      if(!response.ok){
+        const detail=response.status===401?'Sign in again, then check that the server uses the same sign-in provider.':
+          response.status===403?'Check the server’s account permissions and allowed website address.':
+          response.status===404?'The /api/robono route is missing. Run the installer checklist.':
+          response.status===429?'The service is busy or a usage limit was reached. Try again shortly.':
+          'The server could not complete this check. Check its private configuration and permission code.';
+        checks.push({name,status:'failed',detail});return;
+      }
+      checks.push({name,...inspect(await response.json())});
+    }catch{
+      if(signal.aborted)return;
+      checks.push({name,status:'failed',detail:'Could not connect with the current login. Check your server address and internet connection.'});
+    }
+  };
+  await run('Signed-in messaging','settings','messages',data=>({status:data.settings?'passed':'failed',detail:data.settings?'Your current account can load messaging settings.':'The route did not return messaging settings.'}));
+  if(!signal.aborted)await run('Conversations','conversations','messages',data=>({status:!Array.isArray(data.conversations)?'failed':data.conversations.length?'passed':'needs-action',detail:!Array.isArray(data.conversations)?'The route did not return conversations.':data.conversations.length?'Your account has available conversations.':'Connect a second test account and synchronize their permitted relationship from your server.'}));
+  if(!signal.aborted)await run('Notifications','notification-status','notifications',data=>({status:!Array.isArray(data.providers)?'failed':data.providers.length?'passed':'needs-action',detail:!Array.isArray(data.providers)?'Check that the server uses the current messaging package.':data.providers.length?'A notification provider is configured. Test an actual background notification next.':'Connect website or Apple/Google notification settings in Robono. Chat can work before alerts are connected.'}));
+  return checks;
+}
+`,
+        'client/MessengerSetup.tsx': `'use client';
+import React,{useEffect,useRef,useState} from 'react';
+${web ? '' : "import {View,Text,Pressable} from 'react-native';"}
+import type {RobonoAccounts,RobonoAccount} from './ConnectedRobonoChat';
+import {checkMessengerConnection,type ConnectionCheck} from './check-messenger-connection';
+export function MessengerSetup({accounts}:{accounts:RobonoAccounts}){
+  const current=useRef<RobonoAccount|null>(null),generation=useRef(0),pending=useRef<AbortController|null>(null);
+  const [signedIn,setSignedIn]=useState(false),[busy,setBusy]=useState(false),[checks,setChecks]=useState<ConnectionCheck[]>([]);
+  useEffect(()=>{
+    generation.current++;current.current=null;pending.current?.abort();setBusy(false);setChecks([]);setSignedIn(false);
+    let live=true;
+    const off=accounts.subscribe(account=>{
+      if(!live)return;
+      if(current.current?.id!==account?.id){generation.current++;pending.current?.abort();setChecks([]);setBusy(false);}
+      current.current=account;setSignedIn(!!account);
+    });
+    return()=>{live=false;generation.current++;current.current=null;pending.current?.abort();off();};
+  },[accounts]);
+  const run=async()=>{
+    if(!current.current||pending.current&&!pending.current.signal.aborted)return;
+    const account=current.current,version=generation.current,controller=new AbortController();
+    pending.current=controller;setBusy(true);setChecks([]);
+    const timer=setTimeout(()=>controller.abort(),20000);
+    const token=async()=>{
+      if(current.current?.id!==account.id||generation.current!==version)throw Error('Account changed');
+      const value=await current.current.getAccessToken();
+      if(current.current?.id!==account.id||generation.current!==version)throw Error('Account changed');
+      return value;
+    };
+    try{
+      const result=await checkMessengerConnection(token,controller.signal);
+      if(generation.current===version)setChecks(controller.signal.aborted?[{name:'Connection',status:'failed',detail:'The check timed out. Check your connection and try again.'}]:result);
+    }finally{
+      clearTimeout(timer);
+      if(pending.current===controller)pending.current=null;
+      if(generation.current===version)setBusy(false);
+    }
+  };
+  ${web ? `return <aside aria-label="Messenger setup check" style={{padding:12,border:'1px solid #b8b8b8',borderRadius:8,background:'#fff',color:'#222',fontFamily:'system-ui',marginBottom:8}}>
+    <button type="button" disabled={!signedIn||busy} onClick={()=>void run()}>{busy?'Checking connection…':'Check connection'}</button>
+    <p style={{margin:'8px 0',fontSize:14}}>{signedIn?'Uses your current login. No copied tokens or messages.':'Sign in to your app to check the connection.'} Development only.</p>
+    {checks.length>0&&<ul aria-live="polite" style={{margin:0,paddingLeft:20}}>{checks.map(check=><li key={check.name}><strong>{check.status==='passed'?'Ready':check.status==='failed'?'Fix':'Next'} — {check.name}:</strong> {check.detail}</li>)}</ul>}
+    {checks.length>0&&<p style={{fontSize:12,marginBottom:0}}>These are connection checks. They do not prove account isolation, delivery or background notifications.</p>}
+  </aside>;` : `return <View accessibilityLabel="Messenger setup check" style={{padding:12,borderWidth:1,borderColor:'#b8b8b8',borderRadius:8,backgroundColor:'#fff',marginBottom:8}}>
+    <Pressable accessibilityRole="button" accessibilityState={{disabled:!signedIn||busy}} disabled={!signedIn||busy} onPress={()=>void run()} style={{padding:8}}><Text style={{color:'#174ea6',fontWeight:'600'}}>{busy?'Checking connection…':'Check connection'}</Text></Pressable>
+    <Text style={{color:'#222',marginVertical:8}}>{signedIn?'Uses your current login. No copied tokens or messages.':'Sign in to your app to check the connection.'} Development only.</Text>
+    {checks.map(check=><Text key={check.name} style={{color:'#222',marginBottom:6}}>{check.status==='passed'?'Ready':check.status==='failed'?'Fix':'Next'} — {check.name}: {check.detail}</Text>)}
+    {checks.length>0&&<Text style={{color:'#555',fontSize:12}}>These are connection checks. They do not prove account isolation, delivery or background notifications.</Text>}
+  </View>;`}
+}
+`,
+    };
+}
+//# sourceMappingURL=messenger-customer-templates.js.map

package/legacy/0.21.0/messenger-init.js

@@ -0,0 +1,121 @@
+import { connectStarterTemplates } from './messenger-connected-templates.js';
+import { mkdir, writeFile, access, realpath, lstat, rm } from 'node:fs/promises';
+import { resolve, dirname, relative, isAbsolute, join } from 'node:path';
+/** Pure templates contain no credentials. Host authentication deliberately fails closed. */
+export function messengerStarterFiles(options) {
+    const origin = new URL(options.origin);
+    if (origin.origin !== options.origin || origin.username || origin.password || !(origin.protocol === 'https:' || origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname)))
+        throw Error('Use your exact HTTPS website origin, or localhost for development.');
+    if (!['web', 'expo'].includes(options.platform) || !['next', 'fetch'].includes(options.framework) || !options.companyName.trim() || options.companyName.length > 100)
+        throw Error('Choose Website or React Native, your server framework, and a company name.');
+    if (options.platform === 'expo' && origin.protocol !== 'https:')
+        throw Error('Phone apps need an HTTPS server address reachable from the phone.');
+    const q = JSON.stringify, route = options.framework === 'next' ? 'app/api/robono/route.ts' : 'server/robono-route.ts';
+    const auth = `import type {MessengerAccess} from '@robono/server';
+// Replace ONLY these two functions with your existing account/permission service.
+// Do not read a user ID from the request body. Verify expiry and suspension.
+export async function authenticate(request:Request):Promise<string|null>{
+  throw Error('Connect your existing session verification in robono-access.ts');
+}
+// Account operations such as settings, conversations and notifications.register-device
+// have no conversation ID. Allow them only for active, eligible accounts.
+// Chat operations also need current membership and write/read permission checks.
+export async function authorize(access:MessengerAccess):Promise<boolean>{
+  throw Error('Connect your existing messaging permission check in robono-access.ts');
+}
+`;
+    const files = {
+        '.gitignore': '.env\n.env.local\nnode_modules/\n',
+        '.env.example': `# Server only. Never prefix this with NEXT_PUBLIC_, VITE_ or EXPO_PUBLIC_.\nROBONO_API_KEY=\n# Optional comma-separated exact website origins. Set this before deployment.\nROBONO_ALLOWED_ORIGINS=${options.origin}\n`,
+        'server/robono-access.ts': auth,
+        'server/robono.ts': `import {createRobonoMessengerServer} from '@robono/server';
+import {authenticate,authorize} from './robono-access';
+let messenger:ReturnType<typeof createRobonoMessengerServer>|undefined;
+export function getMessenger(){
+ if(messenger)return messenger;
+ const apiKey=process.env.ROBONO_API_KEY;
+ if(!apiKey)throw Error('Set ROBONO_API_KEY on your server.');
+ const allowedOrigins=process.env.ROBONO_ALLOWED_ORIGINS?.split(',').map((value:string)=>value.trim()).filter(Boolean)??[${q(options.origin)}];
+ return messenger=createRobonoMessengerServer({apiKey,authenticate,authorize,allowedOrigins});
+}
+`,
+        [route]: `import {getMessenger} from ${q(options.framework === 'next' ? '../../../server/robono' : './robono')};
+${options.framework === 'next' ? "export const runtime = 'nodejs';\n" : ''}export const GET=(request:Request)=>getMessenger().handle(request);
+export const POST=(request:Request)=>getMessenger().handle(request);
+`,
+        'server/synchronize-contacts.ts': `// Run on your server when your own relationship record changes.
+// Pass the server-only messenger instance from your application. Revisions come from YOUR database.
+export async function synchronizeFriendship(messenger:import('@robono/server').RobonoMessengerServer,friendship:{userA:string;userB:string;canMessage:boolean;revision:number}){
+  return messenger.robono.setRelationship({externalUserIds:[friendship.userA,friendship.userB],allowed:friendship.canMessage,revision:friendship.revision});
+}
+`,
+        'ROBONO-SETUP.md': `# Connect ${options.companyName.replace(/[\r\n]/g, ' ')} to Robono\n\nThese are prepared integration files, not a replacement for your app. No existing files were changed.\n\n1. Install the packages listed below in the corresponding server and client projects.\n2. Copy the generated files into your app. Put the Robono key only in the server's environment.\n3. Connect the two functions in robono-access.ts to your existing sign-in and permission checks. They reject access until connected.\n4. When your app permits or removes a friendship, call synchronizeFriendship with its current revision. Supply current contact names/avatars to the client. Group memberships use messenger.robono.setGroup.\n5. Mount GET and POST at /api/robono. Add the client screen, pass your signed-in account and token-refresh function, and call its signOut() before ending a session.\n6. Run robono-messenger-check against your own route with a disposable test-user token. Then exchange a message between two authorized users.\n\nServer: npm install @robono/server\nTypeScript server: npm install --save-dev typescript @types/node\nClient: npm install @robono/messaging @robono/${options.platform === 'web' ? 'messaging-web react react-dom' : 'messaging-react-native'}\n\n${options.platform === 'expo' ? 'For React Native, follow the native dependency and Expo configuration instructions in the package README before rebuilding iPhone and Android. Your app needs its own Apple/Google notification credentials; upload private keys only in Robono’s notification setup.' : 'For website alerts, enter your HTTPS origin and chat page in Robono’s notification setup. The supplied messenger handles the browser helper. No Apple/Google private key is needed.'}\n\nKeep feature choices in Robono’s Features & preview. Do not duplicate them in frontend permission switches. Your server remains responsible for who may use the service. Never return true for every permission request.\n\n## Local connection check\nSet ROBONO_MESSENGER_URL, ROBONO_TEST_USER_TOKEN and ROBONO_WEBSITE_ORIGIN in your local environment. Then run:\n\n\`\`\`sh\nnpx --package @robono/server robono-messenger-check\n# Shareable diagnostic output; contains no token or message content:\nnpx --package @robono/server robono-messenger-check --json\n\`\`\`\n\n## Assistance\nAn AI coding assistant may use these files and package documentation to connect your existing account service. It must preserve authentication, expiry, suspension, current memberships and server-only keys. It must not replace them with a demo password or an always-allow function. Do not send credentials or customer messages to support chat.\n`,
+    };
+    if (options.platform === 'web')
+        files['client/RobonoChat.tsx'] = `'use client';
+import {useEffect,useRef} from 'react';
+import {mountRobonoMessenger} from '@robono/messaging-web';
+type Options=Parameters<typeof mountRobonoMessenger>[1];
+// Keep getAccessToken and contacts stable. The token callback must return a current token.
+export function RobonoChat({userId,getAccessToken,contacts,onReady}:{userId:string;getAccessToken:Options['getAccessToken'];contacts:Options['contacts'];onReady:(chat:ReturnType<typeof mountRobonoMessenger>|null)=>void}){
+ const element=useRef<HTMLDivElement>(null);
+ useEffect(()=>{
+  if(!element.current)return;
+  const chat=mountRobonoMessenger(element.current,{endpoint:'/api/robono',companyName:${q(options.companyName)},userId,getAccessToken,contacts});
+  onReady(chat);return()=>{onReady(null);chat.unmount();};
+ },[userId,getAccessToken,contacts,onReady]);
+ return <div ref={element} style={{height:'100%',minHeight:400}}/>;
+}
+// Store onReady's chat handle. Await chat.signOut() BEFORE ending your own session.
+`;
+    else
+        files['client/RobonoChat.tsx'] = `import React,{useEffect,useState} from 'react';
+import {createExpoMessenger,ExpoMessenger,type ExpoMessengerProps} from '@robono/messaging-react-native/expo';
+type Connection=ReturnType<typeof createExpoMessenger>;
+export function RobonoChat({userId,getAccessToken,contacts,isCallActive,onReady}:{userId:string;getAccessToken:()=>Promise<string>;contacts:ExpoMessengerProps['contacts'];isCallActive:()=>boolean;onReady:(connection:Connection|null)=>void}){
+ const [active,setActive]=useState<{userId:string;connection:Connection}|null>(null);
+ useEffect(()=>{
+  const connection=createExpoMessenger({endpoint:${q(options.origin + '/api/robono')},userId,getAccessToken,isCallActive});
+  setActive({userId,connection});onReady(connection);
+  return()=>{onReady(null);connection.dispose();};
+ },[userId,getAccessToken,isCallActive,onReady]);
+ if(!active||active.userId!==userId)return null;
+ return <ExpoMessenger {...active.connection} userId={userId} companyName={${q(options.companyName)}} contacts={contacts}/>;
+}
+// Mount inside your app's safe area. Keep callbacks stable. Await connection.signOut()
+// BEFORE ending your session; dispose only detaches the screen.
+`;
+    return connectStarterTemplates(files, options);
+}
+/** All-or-nothing new directory; never edits a customer's existing app or env file. */
+export async function writeMessengerStarter(destination, options) {
+    const files = messengerStarterFiles(options), target = resolve(destination), parent = await realpath(dirname(target));
+    if (join(parent, target.slice(dirname(target).length + 1)) !== target)
+        throw Error('Use a destination without symbolic-link parents.');
+    try {
+        await access(target);
+        throw Error('That directory already exists. Choose a new directory.');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await mkdir(target, { mode: 0o700 });
+    try {
+        for (const [name, content] of Object.entries(files)) {
+            const path = resolve(target, name), local = relative(target, path);
+            if (local.startsWith('..') || isAbsolute(local))
+                throw Error('Invalid template path');
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            if ((await lstat(dirname(path))).isSymbolicLink())
+                throw Error('Unexpected symbolic link');
+            await writeFile(path, content, { flag: 'wx', mode: 0o600 });
+        }
+    }
+    catch (e) {
+        await rm(target, { recursive: true, force: true });
+        throw e;
+    }
+    return Object.keys(files);
+}
+//# sourceMappingURL=messenger-init.js.map

package/legacy/0.21.0/messenger-install.js

@@ -0,0 +1,243 @@
+import { messengerPreviewTemplates } from './messenger-preview-template.js';
+import { readFile, writeFile, mkdir, lstat, realpath, unlink } from 'node:fs/promises';
+import { resolve, join, dirname, relative } from 'node:path';
+import spawn from 'cross-spawn';
+import { messengerStarterFiles } from './messenger-init.js';
+async function exists(file) { try {
+    await lstat(file);
+    return true;
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return false;
+    throw e;
+} }
+async function project(directory) {
+    const root = resolve(directory);
+    if (await realpath(root) !== root)
+        throw Error('Use a project path without symbolic links.');
+    const stat = await lstat(join(root, 'package.json'));
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw Error('Use a regular package.json.');
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    return { root, pkg, deps: { ...pkg.devDependencies, ...pkg.dependencies } };
+}
+async function safePath(file) {
+    let part = resolve(file);
+    while (true) {
+        if (await exists(part)) {
+            const s = await lstat(part);
+            if (s.isSymbolicLink())
+                throw Error('Installation paths cannot contain symbolic links.');
+        }
+        const parent = dirname(part);
+        if (parent === part)
+            break;
+        part = parent;
+    }
+}
+async function appRoot(root) {
+    for (const base of ['src', ''])
+        if (await exists(join(root, base, 'app'))) {
+            await safePath(join(root, base, 'app'));
+            return base;
+        }
+    throw Error('Automatic website installation supports Next.js App Router. Create its app directory first, or use robono-messenger-init for another server.');
+}
+function installCommand(root, manager, packages) {
+    if (!['npm', 'pnpm', 'yarn'].includes(manager))
+        throw Error('Supported package managers: npm, pnpm, yarn.');
+    return { cwd: root, command: manager, args: manager === 'npm' ? ['install', '--ignore-scripts', '--', ...packages] : manager === 'pnpm' ? ['add', '--ignore-scripts', '--', ...packages] : ['add', '--ignore-scripts', ...packages] };
+}
+async function manager(root, pkg) {
+    const locks = [];
+    for (const [file, name] of [['package-lock.json', 'npm'], ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn']])
+        if (await exists(join(root, file)))
+            locks.push(name);
+    const named = pkg.packageManager?.split('@')[0];
+    if (locks.length > 1 || named && locks.length && locks[0] !== named)
+        throw Error('Conflicting package-manager files. Keep the lockfile used by this project before installing.');
+    const result = named ?? locks[0] ?? 'npm';
+    // Yarn Berry has different script controls; do not silently run hooks or rewrite its configuration.
+    if (result === 'yarn' && pkg.packageManager && !pkg.packageManager.startsWith('yarn@1.'))
+        throw Error('Use the generated-file command for Yarn 2+; automatic installation currently supports Yarn 1, npm and pnpm.');
+    return result;
+}
+export async function planMessengerInstallation(options) {
+    return createInstallationPlan(options, false);
+}
+async function createInstallationPlan(options, resume) {
+    if (Number(process.versions.node.split('.')[0]) < 22)
+        throw Error('Use Node.js 22 or later for automatic installation.');
+    const client = await project(options.project), platform = client.deps.expo ? 'expo' : client.deps.next ? 'web' : null;
+    if (!platform)
+        throw Error('Automatic installation supports Next.js App Router and Expo. For other projects use robono-messenger-init.');
+    if (platform === 'expo' && !/^[~^]?(55|56)\./.test(client.deps.expo))
+        throw Error('The supplied Expo messenger supports Expo 55–56. Keep your current app unchanged and check the mobile installation guide.');
+    if (platform === 'expo' && !options.serverProject)
+        throw Error('Pass --server-project with your existing Next.js server folder. A phone app must not contain the Robono server key.');
+    const server = platform === 'web' ? client : await project(options.serverProject);
+    if (!server.deps.next)
+        throw Error('The automatic server connection needs Next.js App Router. Use robono-messenger-init for other servers.');
+    if (platform === 'expo' && server.root === client.root)
+        throw Error('Use a separate server project; never install server credentials inside the phone app.');
+    const serverBase = await appRoot(server.root), clientBase = platform === 'web' ? serverBase : (await exists(join(client.root, 'src')) ? 'src' : '');
+    const detected = client.deps['@supabase/supabase-js'] ? 'supabase' : client.deps.firebase ? 'firebase' : 'custom';
+    if (!options.auth && client.deps['@supabase/supabase-js'] && client.deps.firebase)
+        throw Error('Both sign-in providers are installed. Choose --auth supabase, firebase or custom.');
+    const auth = options.auth ?? detected;
+    const providerName = auth === 'supabase' ? '@supabase/supabase-js' : auth === 'firebase' ? 'firebase' : null;
+    if (providerName && client.deps[providerName]) {
+        const installed = await readFile(join(client.root, 'node_modules', providerName, 'package.json'), 'utf8').then(value => JSON.parse(value).version).catch(() => client.deps[providerName]);
+        const major = Number(installed.match(/^[~^]?(\d+)/)?.[1]);
+        if (!major || major < (auth === 'supabase' ? 2 : 9))
+            throw Error('This sign-in package needs a newer API. Keep your current sign-in unchanged and use --auth custom, or update it separately.');
+    }
+    const templates = messengerStarterFiles({ platform, framework: 'next', origin: options.origin, companyName: options.companyName, auth });
+    const files = [], replacements = [];
+    for (const [name, content] of Object.entries(templates)) {
+        if (name.startsWith('client/'))
+            files.push({ path: join(client.root, clientBase, 'robono', name), content });
+        else if (name.startsWith('server/'))
+            files.push({ path: join(server.root, serverBase, 'robono', name), content });
+    }
+    files.push({ path: join(server.root, serverBase, 'app/api/robono/route.ts'), content: templates['app/api/robono/route.ts'].replace('../../../server/robono', '../../../robono/server/robono') });
+    const preview = messengerPreviewTemplates();
+    files.push({ path: join(server.root, serverBase, 'app/robono-preview/page.tsx'), content: preview.page }, { path: join(server.root, serverBase, 'robono/client/RobonoPreview.tsx'), content: preview.client });
+    const notes = [`Detected ${platform === 'web' ? 'Next.js website' : 'Expo phone app'} and ${auth} sign-in.`,
+        'Start your Next.js development server and open /robono-preview for the two-person local example. It returns 404 in production.',
+        'Connect your current messaging permission check in robono/server/robono-access.ts. Access stays blocked until then.',
+        'Keep provider credentials and the Robono key on the server. The installer never reads or edits your .env files.',
+        'Mount CustomerMessenger with your existing sign-in client and contacts. Account wiring is included.',
+        'Connect website alerts or Apple/Google credentials in Robono → Your app → Message notifications. Chat works before alerts are configured.'];
+    const setup = { schema: 2, platform, auth, companyName: options.companyName, origin: options.origin, serverProject: relative(client.root, server.root) || '.', dependencies: 'pending', checks: { files: 'installed', permissions: 'needs-connection', serverKey: 'needs-server-environment', contacts: 'needs-connection', notifications: 'needs-configuration', liveConnection: 'not-tested' } };
+    files.push({ path: join(client.root, '.robono/setup.json'), content: JSON.stringify(setup, null, 2) + '\n' });
+    files.push({ path: join(client.root, '.robono/SETUP.md'), content: '# Connect your messenger\n\n' + notes.map(x => '- ' + x).join('\n') + '\n\n## Connect your screen\n' + (auth === 'custom' ? 'Implement RobonoAccounts from client/ConnectedRobonoChat.tsx using your existing sign-in. Render <CustomerMessenger accounts={yourAccounts} contacts={yourContacts}/>.' : 'Import CustomerMessenger from the generated client/CustomerMessenger.tsx. Render <CustomerMessenger auth={yourExistingSignInClient} contacts={yourContacts}/>.') + ' Give the messenger an area with a height. Keep it mounted in your signed-in application. It follows account changes; names and avatars update without restarting chat. For Supabase use its client; for Firebase use its Auth instance.\n\n## Allow the right people\nConnect authorize in robono-access.ts to current account eligibility, suspension and conversation permissions. It denies access until implemented. When a friendship changes, call synchronizeFriendship(getMessenger(), friendship) on your server. Use revisions from your database; group membership uses getMessenger().robono.setGroup. Never use an always-allow function.\n\n## Sign-out\nThe messenger account menu clears local content and unregisters notifications before provider sign-out. If your own account menu signs out first, provider events still clear the visible chat. Keep account suspension and relationship revocation synchronized with Robono; an expired session cannot reliably unregister a remote device. Never substitute another account’s token.\n\n## Check the connection\nDuring development, add setupChecks to CustomerMessenger and press Check connection after signing in to your app. It uses your current login; no copied tokens are needed. It checks settings, available chats and notification configuration without sending a message. This optional panel is hidden in production.\n\nRun robono-messenger-install --check for the local checklist. For additional command-line security checks, set ROBONO_MESSENGER_URL, ROBONO_WEBSITE_ORIGIN and ROBONO_TEST_USER_TOKEN locally. Add --json for a shareable report without secrets. No local checker can prove your complete permission rules; test denied accounts and cross-account access too.\n\n## Interrupted installation\nRun robono-messenger-install --resume from the same project. It reinstalls the required packages without replacing your integration code, screens or environment files.\n\n## Server configuration\nSet ROBONO_API_KEY privately on the server. Use ROBONO_ALLOWED_ORIGINS for your production website addresses instead of editing generated code. Never use a wildcard. Existing Next.js Supabase public settings are reused; see server.env.example.\n\n## Notifications\nFor website alerts configure your HTTPS origin and chat path. For iPhone, upload your APNs .p8 key, key ID, Team ID and Bundle ID in Robono. For Android, configure google-services.json in your app and upload the Firebase messaging service account privately in Robono. Never put private keys in client code. Build both apps after native dependency changes.\n\n## Local preview\nOpen /robono-preview on your Next.js development server. It uses the actual web messenger with fictional Alice and Bob and local text only. It sends no customer requests and returns 404 in production.\n' });
+    files.push({ path: join(server.root, '.robono/server.env.example'), content: templates['.env.example'] });
+    const serverPackages = ['@robono/server@^0.21.0', ...(platform === 'expo' ? ['@robono/messaging@^0.4.1', '@robono/messaging-web@^0.6.0'] : []), ...(auth === 'supabase' ? ['@supabase/supabase-js@^2'] : auth === 'firebase' ? ['firebase-admin@^14'] : [])];
+    const clientPackages = ['@robono/messaging@^0.4.1', `@robono/messaging-${platform === 'web' ? 'web' : 'react-native'}@^0.6.0`, ...(auth === 'supabase' ? ['@supabase/supabase-js@^2'] : auth === 'firebase' ? ['firebase@^13'] : [])];
+    const packageName = (spec) => spec.slice(0, spec.lastIndexOf('@'));
+    const keepExistingProvider = (spec, deps) => !['firebase', 'firebase-admin', '@supabase/supabase-js'].includes(packageName(spec)) || !deps[packageName(spec)];
+    const serverInstall = serverPackages.filter(spec => keepExistingProvider(spec, server.deps)), clientInstall = clientPackages.filter(spec => keepExistingProvider(spec, client.deps));
+    const commands = [];
+    if (platform === 'web')
+        commands.push(installCommand(client.root, await manager(client.root, client.pkg), [...new Set([...serverInstall, ...clientInstall])]));
+    else {
+        commands.push(installCommand(server.root, await manager(server.root, server.pkg), serverInstall));
+        const cm = await manager(client.root, client.pkg);
+        commands.push(installCommand(client.root, cm, clientInstall));
+        // Expo selects versions compatible with the customer's installed SDK, not arbitrary latest peers.
+        commands.push({ cwd: client.root, command: process.execPath, args: [join(client.root, 'node_modules/expo/bin/cli'), 'install', 'expo-audio', 'expo-image-picker', 'expo-document-picker', 'expo-file-system', 'expo-sharing', 'expo-video', 'expo-crypto', 'react-native-safe-area-context', 'react-native-svg', 'expo-clipboard', 'expo-image-manipulator', 'expo-video-thumbnails', 'react-native-webview', 'expo-blur', 'expo-notifications', 'expo-secure-store', '--' + cm] });
+        if (await exists(join(client.root, 'app.config.js')) || await exists(join(client.root, 'app.config.ts')))
+            throw Error('Your Expo configuration is code. Use robono-messenger-init and the mobile guide so your existing configuration is preserved.');
+        const configPath = join(client.root, 'app.json');
+        await safePath(configPath);
+        const before = await readFile(configPath, 'utf8'), config = JSON.parse(before);
+        if (!config.expo || typeof config.expo !== 'object' || Array.isArray(config.expo))
+            throw Error('Expected an expo configuration object in app.json.');
+        const plugins = config.expo?.plugins ?? [];
+        if (!Array.isArray(plugins))
+            throw Error('Expected an Expo plugins array in app.json.');
+        const names = plugins.map(p => Array.isArray(p) ? p[0] : p);
+        const required = [['expo-audio', { microphonePermission: 'Allow microphone access to record voice messages.', enableBackgroundRecording: false }], ['expo-image-picker', { cameraPermission: 'Allow camera access to take photos and videos for messages.' }], 'expo-notifications', '@robono/messaging-react-native'];
+        const added = required.filter(p => !names.includes(Array.isArray(p) ? p[0] : p));
+        if (added.length) {
+            config.expo.plugins = [...plugins, ...added];
+            replacements.push({ path: configPath, before, after: JSON.stringify(config, null, 2) + '\n' });
+            files.push({ path: join(client.root, '.robono/app.json.before-install'), content: before });
+        }
+        notes.push('Added missing Expo plugins; existing permission wording is preserved. Rebuild both iPhone and Android after native dependency changes.');
+    }
+    if (!resume)
+        for (const file of files) {
+            await safePath(file.path);
+            if (await exists(file.path))
+                throw Error(`Already exists: ${file.path}. Nothing was changed. Use --check to see the remaining steps, or --resume to finish package installation.`);
+        }
+    return { platform, auth, files: resume ? [] : files, replacements: resume ? [] : replacements, commands, notes: resume ? ['Resume package installation. Existing integration files, permission code, screens and environment files are preserved.'] : notes, setupFile: join(client.root, '.robono/setup.json') };
+}
+/** Reconstruct trusted package commands; never execute commands from saved metadata. */
+export async function planMessengerInstallationResume(directory) {
+    const root = resolve(directory), setupFile = join(root, '.robono/setup.json');
+    await safePath(setupFile);
+    const setup = JSON.parse(await readFile(setupFile, 'utf8'));
+    if (![1, 2].includes(setup.schema) || !['web', 'expo'].includes(setup.platform) || !['custom', 'supabase', 'firebase'].includes(setup.auth) || typeof setup.origin !== 'string' || typeof setup.serverProject !== 'string' || setup.companyName !== undefined && typeof setup.companyName !== 'string')
+        throw Error('Invalid saved setup. Keep your integration files and run --check.');
+    const server = resolve(root, setup.serverProject), base = await appRoot(server);
+    const clientBase = setup.platform === 'web' ? base : (await exists(join(root, 'src')) ? 'src' : '');
+    for (const file of [join(root, clientBase, 'robono/client/ConnectedRobonoChat.tsx'), join(server, base, 'app/api/robono/route.ts')]) {
+        await safePath(file);
+        if (!await exists(file))
+            throw Error('An integration file is missing. Restore it before resuming; existing code was not changed.');
+    }
+    return createInstallationPlan({ project: root, ...(setup.platform === 'expo' ? { serverProject: server } : {}), origin: setup.origin, companyName: setup.companyName ?? 'Your company', auth: setup.auth }, true);
+}
+/** Preflight all files; exclusive writes and rollback avoid overwriting customer work. */
+export async function applyMessengerInstallation(plan, install = true) {
+    for (const file of plan.files) {
+        await safePath(file.path);
+        if (await exists(file.path))
+            throw Error(`Already exists: ${file.path}. Nothing was changed.`);
+    }
+    for (const file of plan.replacements) {
+        await safePath(file.path);
+        if (await readFile(file.path, 'utf8') !== file.before)
+            throw Error('Project configuration changed after planning. Run the installer again.');
+    }
+    const written = [], replaced = [];
+    try {
+        for (const file of plan.files) {
+            await mkdir(dirname(file.path), { recursive: true });
+            await writeFile(file.path, file.content, { flag: 'wx', mode: 0o600 });
+            written.push(file.path);
+        }
+        for (const file of plan.replacements) {
+            if (await readFile(file.path, 'utf8') !== file.before)
+                throw Error('Project configuration changed during installation. Existing configuration was preserved.');
+            await writeFile(file.path, file.after);
+            replaced.push(file);
+        }
+    }
+    catch (e) {
+        for (const file of replaced)
+            await writeFile(file.path, file.before);
+        for (const file of written)
+            await unlink(file);
+        throw e;
+    }
+    if (install)
+        for (const command of plan.commands)
+            await new Promise((resolve, reject) => {
+                const child = spawn(command.command, command.args, { cwd: command.cwd, stdio: 'inherit', shell: false, env: { ...process.env, npm_config_ignore_scripts: 'true', YARN_ENABLE_SCRIPTS: 'false' } });
+                child.on('error', () => reject(Error('Package installation could not start. Files are saved; fix the package-manager error and run robono-messenger-install --resume.')));
+                child.on('exit', code => code === 0 ? resolve() : reject(Error('Package installation did not finish. Files are saved; fix the package-manager error and run robono-messenger-install --resume.')));
+            });
+    if (install && plan.setupFile) {
+        await safePath(plan.setupFile);
+        const setup = JSON.parse(await readFile(plan.setupFile, 'utf8'));
+        setup.dependencies = 'installed';
+        await writeFile(plan.setupFile, JSON.stringify(setup, null, 2) + '\n');
+    }
+}
+export async function messengerInstallationChecklist(directory) {
+    const root = resolve(directory), file = join(root, '.robono/setup.json');
+    if (!await exists(file))
+        return [{ name: 'Install files', status: 'needs-action', detail: 'Run robono-messenger-install in your Next.js or Expo project.' }];
+    const setup = JSON.parse(await readFile(file, 'utf8'));
+    const server = resolve(root, setup.serverProject), base = await appRoot(server);
+    const permissionFile = join(server, base, 'robono/server/robono-access.ts');
+    const permission = await readFile(permissionFile, 'utf8').catch(() => 'Connect your existing messaging permission');
+    const missingPermission = permission.includes('Connect your existing messaging permission');
+    const clientBase = setup.platform === 'web' ? base : (await exists(join(root, 'src')) ? 'src' : '');
+    const complete = await exists(join(root, clientBase, 'robono/client/ConnectedRobonoChat.tsx')) && await exists(join(server, base, 'app/api/robono/route.ts'));
+    return [
+        { name: 'Prepared files', status: complete ? 'passed' : 'failed', detail: `${setup.platform === 'expo' ? 'Expo' : 'Next.js'}; ${setup.auth} sign-in.` },
+        { name: 'Package installation', status: setup.dependencies === 'installed' ? 'configured' : 'needs-action', detail: setup.dependencies === 'installed' ? 'The package manager completed. Use the in-app connection check next.' : 'Run robono-messenger-install --resume to finish installing packages without replacing your integration files.' },
+        { name: 'Account permissions', status: missingPermission ? 'needs-action' : 'configured', detail: missingPermission ? 'Connect robono-access.ts to your current permission rules. The live checker verifies a test account.' : 'Permission code was edited. Verify allowed and denied accounts; file inspection cannot prove your rules.' },
+        { name: 'Server key', status: 'needs-action', detail: 'Set ROBONO_API_KEY on the server. This command does not read or print secrets.' },
+        { name: 'Contacts', status: 'needs-action', detail: 'Synchronize permitted friendships and group membership; pass names/avatars to ConnectedRobonoChat.' },
+        { name: 'Notifications', status: 'needs-action', detail: setup.platform === 'expo' ? 'Add Apple/Google credentials in Robono and rebuild both apps with the installed Expo plugins.' : 'Connect your website origin and chat path in Robono.' },
+        { name: 'Live connection', status: 'needs-action', detail: 'Set ROBONO_MESSENGER_URL, ROBONO_WEBSITE_ORIGIN and ROBONO_TEST_USER_TOKEN locally, then run robono-messenger-check.' },
+    ];
+}
+//# sourceMappingURL=messenger-install.js.map

package/legacy/0.21.0/messenger-preview-template.js

@@ -0,0 +1,43 @@
+/** Development-only, in-memory demonstration using the actual shipped messenger. */
+export function messengerPreviewTemplates() {
+    return {
+        page: `import {notFound} from 'next/navigation';
+import Preview from '../../robono/client/RobonoPreview';
+export const dynamic='force-dynamic';
+export default function RobonoPreviewPage(){if(process.env.NODE_ENV!=='development')notFound();return <Preview/>;}
+`,
+        client: `'use client';
+import React,{useEffect,useRef} from 'react';
+import {mountRobonoMessenger} from '@robono/messaging-web';
+import {defaultMessagingSettings} from '@robono/messaging';
+export default function RobonoPreview(){
+ const alice=useRef<HTMLDivElement>(null),bob=useRef<HTMLDivElement>(null);
+ useEffect(()=>{
+  if(process.env.NODE_ENV!=='development'||!alice.current||!bob.current)return;
+  const settings=defaultMessagingSettings();settings.enabled=true;
+  const messages:any[]=[];
+  const transport=(userId:string):typeof fetch=>async(_request,init)=>{
+   const body=JSON.parse(String(init?.body??'{}')),other=userId==='alice'?'bob':'alice';let result:unknown;
+   switch(body.operation){
+    case 'settings':result={settings};break;
+    case 'conversations':result={appearance:settings.appearance,conversations:[{id:'demo-chat',kind:'direct',contactId:other,lastMessage:messages.at(-1)??null,unreadCount:0,canSend:true}],hasMore:false,nextCursor:null};break;
+    case 'list':result={settings,messages:[...messages],hasMore:false,nextCursor:null,conversation:{kind:'direct',canSend:true}};break;
+    case 'send':{
+     let message=messages.find(m=>m.senderId===userId&&m.clientMessageId===body.clientMessageId);
+     if(!message){message={...body,id:String(messages.length+1),senderId:userId,createdAt:new Date().toISOString(),readAt:null};messages.push(message);}
+     result={message};break;
+    }
+    case 'read':for(const m of messages)if(m.senderId!==userId)m.readAt=new Date().toISOString();result={ok:true};break;
+    default:return Response.json({error:'This local preview demonstrates text only. Connect your test account to try other features.'},{status:400});
+   }
+   return Response.json(result);
+  };
+  const mount=(element:HTMLDivElement,userId:string)=>mountRobonoMessenger(element,{companyName:'Example company',userId,getAccessToken:async()=>'local-preview-only',contacts:{alice:{name:'Alice'},bob:{name:'Bob'}},endpoint:'/local-preview-never-sent',fetch:transport(userId),notifications:false,mediaUrl:false,persistence:false});
+  const a=mount(alice.current,'alice'),b=mount(bob.current,'bob');return()=>{a.unmount();b.unmount();};
+ },[]);
+ return <main style={{padding:16,fontFamily:'system-ui'}}><h1>Try a conversation</h1><p>Local preview · Fictional Alice and Bob · Text stays in this page and disappears on reload. This does not test your live connection.</p><p>Open Bob on the left and Alice on the right, then send a message.</p><div style={{display:'flex',flexWrap:'wrap',gap:16}}><section style={{flex:'1 1 320px'}}><h2>Alice</h2><div ref={alice} style={{height:640}}/></section><section style={{flex:'1 1 320px'}}><h2>Bob</h2><div ref={bob} style={{height:640}}/></section></div></main>;
+}
+`
+    };
+}
+//# sourceMappingURL=messenger-preview-template.js.map

package/legacy/0.21.0/package.json

@@ -0,0 +1 @@
+{"type":"module","private":true}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robono/server",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Provider-neutral server SDK for the Robono Bridge API.",
   "keywords": [
     "robono",
@@ -43,6 +43,14 @@
     "./installer": {
       "types": "./dist/messenger-install.d.ts",
       "import": "./dist/messenger-install.js"
+    },
+    "./node": {
+      "types": "./dist/messenger-node.d.ts",
+      "import": "./dist/messenger-node.js"
+    },
+    "./upgrade": {
+      "types": "./dist/messenger-upgrade.d.ts",
+      "import": "./dist/messenger-upgrade.js"
     }
   },
   "bin": {
@@ -60,7 +68,8 @@
     "SBOM.spdx.json",
     "sql",
     "NOTIFICATIONS.md",
-    "SCREENING.md"
+    "SCREENING.md",
+    "legacy"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",