@byokit/realtime 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.2.1 (2026-09-30)
+
+
+
+- FIX: Report saved-sign-in failure reasons and plain remedies in advisory auth checks while preserving existing status results.
+
 ## 0.2.0 (2026-09-30)
 
 

package/README.md

@@ -85,28 +85,40 @@ The app's `peek` callback must also never refresh, prompt or start login.
 
 ```ts
 import { realtimeEngine, toolBridge } from '@byokit/realtime/node';
-import type { RealtimeAuth, RealtimeHostFrame, RealtimeTool } from '@byokit/realtime';
+import type { RealtimeAuth, RealtimeHostFrame, RealtimeTool, RealtimeAuthPeekResult, RealtimeAuthResult } from '@byokit/realtime';
 
 declare const auth: Extract<RealtimeAuth, { kind: 'plan' }>;
 declare const tools: RealtimeTool[];
 declare const bridge: ReturnType<typeof toolBridge>;
 declare const emit: (frame: RealtimeHostFrame) => void;
-declare const peekSavedSignIn: (signal: AbortSignal) => Promise<boolean>;
+declare const peekSavedSignIn: (signal: AbortSignal) => Promise<RealtimeAuthPeekResult>;
 declare const updateSettingsBadge: (status: 'ready' | 'signed-out' | 'unknown') => void;
+declare const showSignInMessage: (result: RealtimeAuthResult) => void;
 const engine = realtimeEngine({
   engine: 'chatgpt', auth,
   tools, bridge, emit,
-  authCheck: { peek: peekSavedSignIn, onStatus: status => updateSettingsBadge(status) },
+  authCheck: { peek: peekSavedSignIn, onStatus: status => updateSettingsBadge(status), onResult: showSignInMessage },
 });
 ```
 
 `ready` means the app reports a saved sign-in, not provider entitlement.
-`signed-out` means the lookup returned false. Errors or a timeout produce
-`unknown`; the default timeout is one second, capped at ten seconds. Close
+`signed-out` means the lookup returned false or found an unusable saved sign-in.
+Unrecognized errors or a timeout produce `unknown`; the default timeout is one second, capped at ten seconds. Close
 cancels pending checks and suppresses late notifications. Normal session
 authentication still needs the credential from `auth.access`.
 For a standalone settings lookup, `realtimeAuthCheck({ peek })` is also exported
-from the portable entry and returns `{ result, close }`. Do not await this check
+from the portable entry and returns `{ result, details, close }`. `result` still
+resolves to the status string; `details` resolves to `{ state, reason?, message? }`,
+and engine `onResult` receives the same diagnostic object. A boolean or
+`{ state }` peek keeps the previous behavior without adding a reason.
+
+To report an expired saved sign-in, the read-only peek can return
+`{ state: 'signed-out', reason: 'login-expired' }`. Built-in reasons are
+`credential-permissions`, `login-expired`, `missing` and `unknown`; apps can
+supply additional reason strings. Messages use fixed plain wording and never
+copy exception text or credential paths. Missing-file errors map to `missing`,
+permission errors to `credential-permissions`, and expired-login errors to
+`login-expired`; unrecognized errors and timeouts report `unknown`. Do not await this check
 before opening a voice session or show a login prompt from its result.
 
 ## Lifecycle announcements and semantic app tools

package/dist/auth.d.ts

@@ -1,7 +1,20 @@
 export type RealtimeAuthStatus = 'ready' | 'signed-out' | 'unknown';
+/** Additional app-defined reasons are allowed without changing the state contract. */
+export type RealtimeAuthReason = 'credential-permissions' | 'login-expired' | 'missing' | 'unknown' | (string & {});
+export type RealtimeAuthResult = {
+    state: RealtimeAuthStatus;
+    reason?: RealtimeAuthReason;
+    message?: string;
+};
+export type RealtimeAuthPeekResult = boolean | {
+    state: RealtimeAuthStatus;
+    reason?: RealtimeAuthReason;
+};
 export type RealtimeAuthCheckOptions = {
     /** Read-only saved-sign-in check. Must never start login, refresh access or prompt. */
-    peek(signal: AbortSignal): Promise<boolean>;
+    peek(signal: AbortSignal): Promise<RealtimeAuthPeekResult>;
+    /** Diagnostic observer, also available through the standalone details promise. */
+    onResult?(result: RealtimeAuthResult): void;
     onStatus?(status: RealtimeAuthStatus): void;
     /** Defaults to 1 second; capped at 10 seconds. */
     timeoutMs?: number;
@@ -9,5 +22,6 @@ export type RealtimeAuthCheckOptions = {
 /** Advisory only: session startup must proceed independently of this check. */
 export declare function realtimeAuthCheck(options: RealtimeAuthCheckOptions): {
     result: Promise<RealtimeAuthStatus>;
+    details: Promise<RealtimeAuthResult>;
     close(): void;
 };

package/dist/auth.js

@@ -1,29 +1,58 @@
+function describe(state, reason) {
+    if (!reason)
+        return { state };
+    const message = reason === 'credential-permissions' ? 'Your saved sign-in must be readable only by you.'
+        : reason === 'login-expired' ? 'Your saved sign-in has expired. Sign in again in settings.'
+            : reason === 'missing' ? 'No saved sign-in was found. Sign in in settings.'
+                : 'Your saved sign-in could not be checked.';
+    return { state, reason, message };
+}
+function failure(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+    const reason = error && typeof error === 'object' && 'reason' in error ? error.reason : undefined;
+    if (reason === 'credential-permissions' || reason === 'login-expired' || reason === 'missing' || reason === 'unknown')
+        return describe(reason === 'unknown' ? 'unknown' : 'signed-out', reason);
+    if (code === 'ENOENT')
+        return describe('signed-out', 'missing');
+    if (code === 'EACCES' || code === 'EPERM' || code === 'credential-permissions' || (error instanceof Error && /owner.only|readable only by|permissions.*(?:credential|sign-in)|(?:credential|sign-in).*permissions/i.test(error.message)))
+        return describe('signed-out', 'credential-permissions');
+    if (code === 'login-expired' || code === 'TOKEN_EXPIRED' || (error instanceof Error && /\b(?:login|sign-in|token|credential)\b.*\bexpired\b/i.test(error.message)))
+        return describe('signed-out', 'login-expired');
+    return describe('unknown', 'unknown');
+}
 /** Advisory only: session startup must proceed independently of this check. */
 export function realtimeAuthCheck(options) {
     const controller = new AbortController();
     let settled = false;
     let resolve;
     const result = new Promise(done => { resolve = done; });
-    const finish = (status, notify = true) => {
+    let resolveDetails;
+    const details = new Promise(done => { resolveDetails = done; });
+    const finish = (value, notify = true) => {
         if (settled)
             return;
         settled = true;
         clearTimeout(timer);
         controller.abort();
-        resolve(status);
+        resolve(value.state);
+        resolveDetails(value);
         // A settings observer cannot fail a call or create an unhandled rejection.
         if (notify) {
             try {
-                options.onStatus?.(status);
+                options.onStatus?.(value.state);
+            }
+            catch { }
+            try {
+                options.onResult?.(value);
             }
             catch { }
         }
     };
     const timeout = options.timeoutMs ?? 1000;
-    const timer = setTimeout(() => finish('unknown'), Number.isFinite(timeout) ? Math.min(10000, Math.max(1, timeout)) : 1000);
+    const timer = setTimeout(() => finish(describe('unknown', 'unknown')), Number.isFinite(timeout) ? Math.min(10000, Math.max(1, timeout)) : 1000);
     void Promise.resolve().then(() => {
         if (!settled)
             return options.peek(controller.signal);
-    }).then(value => finish(value === true ? 'ready' : value === false ? 'signed-out' : 'unknown'), () => finish('unknown'));
-    return { result, close() { finish('unknown', false); } };
+    }).then(value => finish(typeof value === 'object' && value !== null ? describe(value.state, value.reason) : describe(value === true ? 'ready' : value === false ? 'signed-out' : 'unknown')), error => finish(failure(error)));
+    return { result, details, close() { finish(describe('unknown', 'unknown'), false); } };
 }

package/dist/node.d.ts

@@ -5,7 +5,7 @@ import { toolBridge } from './tools.ts';
 import type { RealtimeAuthCheckOptions } from './auth.ts';
 export { toolBridge, appBridge, delegationHandler } from './tools.ts';
 export { realtimeAuthCheck } from './auth.ts';
-export type { RealtimeAuthCheckOptions, RealtimeAuthStatus } from './auth.ts';
+export type { RealtimeAuthCheckOptions, RealtimeAuthStatus, RealtimeAuthReason, RealtimeAuthResult, RealtimeAuthPeekResult } from './auth.ts';
 export type { ToolHandler, ToolBridgeOptions } from './tools.ts';
 export type { RealtimeSignalingIdentity } from './adapter.ts';
 export type RealtimeEngineOptions = RealtimeConfig & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/realtime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Realtime voice sessions with host-held credentials and injected audio.",
   "license": "Apache-2.0",
   "type": "module",