@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/app/app.tsx

@@ -0,0 +1,232 @@
+import { type Apis, type DeviceBackends } from './apis/index.ts';
+import {
+  type AuthApp,
+  createApp as assemble,
+  type PublicApp,
+} from './assemble/index.ts';
+import { type GateView } from './gate/index.ts';
+import { type SessionDef } from './session/index.ts';
+import { type Storage } from './host/index.ts';
+import type { ReactNode } from 'react';
+import {
+  type RootPlugin,
+  webRoot,
+  type WebRootOptions,
+} from '../client/index.ts';
+import { pwaRoot } from '../pwa/index.ts';
+import { AccountLost } from '../recipes/account-lost/index.ts';
+import { type GateScreen, GateScreens } from '../recipes/gate-screens/index.ts';
+import {
+  LocalSignIn,
+  type LocalSignInChoice,
+} from '../recipes/local-sign-in/index.ts';
+import { createTheme } from '../theme/index.ts';
+import { webHost } from './web-host.ts';
+
+/** Signing in, for an app that has Accounts. */
+export interface WebAuth<A extends Apis, S> {
+  /** The shared sign-in service. */
+  readonly url: string;
+  /** What one Account keeps while it is active. */
+  readonly session?: SessionDef<A, S>;
+  /** Who to try the device Backend as, in one tap. */
+  readonly presets?: ReadonlyArray<LocalSignInChoice>;
+}
+
+/** What a web app gives `createApp`. Everything else is given: the Theme,
+ * the PWA, the screens before an Account is open. */
+export interface WebAppConfig<A extends Apis, S, C> {
+  /** Names what the app keeps on the device and tells its other tabs. */
+  readonly name: string;
+  /** The app's name, as people read it: every page's title. */
+  readonly title: string;
+  /** One line on what the app is for, under its name before sign-in. */
+  readonly description?: string;
+  /** The app's mark, above its name before sign-in. */
+  readonly mark?: ReactNode;
+  readonly apis?: A;
+  /** The device Backend: every API's handlers on the device's Storage. */
+  readonly device?: (
+    storage: Storage,
+  ) => DeviceBackends<A> | Promise<DeviceBackends<A>>;
+  readonly auth?: WebAuth<A, S>;
+  /** What only this device keeps, such as Settings. */
+  readonly cache?: (storage: Storage) => C;
+  /** The Theme's cookie is shared by every app under `cookieDomain`. */
+  readonly theme?: { readonly cookieDomain?: string | undefined };
+  /** The PWA is always on; this says how it asks to be installed. */
+  readonly pwa?: { readonly installTitle?: string };
+}
+
+/** What `root` takes from the root route's file. */
+export type RootOptions = Pick<
+  WebRootOptions,
+  'stylesheet' | 'icon' | 'loadTheme' | 'notFound'
+>;
+
+type NotOpen<S> = Exclude<GateView<S>, { kind: 'open' }>;
+
+const screenOf = (
+  view: Exclude<NotOpen<unknown>, { kind: 'accountLost' }>,
+): GateScreen => {
+  switch (view.kind) {
+    case 'checking':
+    case 'signingOut':
+      return { kind: view.kind };
+    case 'opening':
+    case 'unopenable':
+      return { kind: view.kind, name: view.account.user.name };
+    case 'signedOut':
+      return { kind: 'signedOut', unreachable: view.unreachable };
+  }
+};
+
+/**
+ * A web app: a PWA on TanStack Start in the app's Theme, with its APIs on
+ * the cloud Backend at this origin or on the device Backend in the page,
+ * and, with `auth`, several Accounts signed in on this device, one Session
+ * each. `root` is the root route; `SignedIn` wraps what needs an Account
+ * and shows the right screen otherwise. Make one per app, in `app.ts`.
+ */
+export function createApp<A extends Apis, S, C = never>(
+  config: WebAppConfig<A, S, C> & { readonly auth: WebAuth<A, S> },
+): WebAuthApp<A, S, C>;
+export function createApp<A extends Apis, C = never>(
+  config: WebAppConfig<A, never, C> & { readonly auth?: undefined },
+): WebPublicApp<A, C>;
+export function createApp<A extends Apis, S, C>(
+  config: WebAppConfig<A, S, C>,
+): WebAuthApp<A, S, C> | WebPublicApp<A, C> {
+  const theme = createTheme(
+    config.theme?.cookieDomain === undefined
+      ? {}
+      : { cookieDomain: config.theme.cookieDomain },
+  );
+  const host = () => webHost({ name: config.name, authUrl: config.auth?.url });
+  const parts = {
+    host,
+    ...(config.apis !== undefined && { apis: config.apis }),
+    ...(config.device !== undefined && { device: config.device }),
+    ...(config.cache !== undefined && { cache: config.cache }),
+  };
+  const pwa = pwaRoot(
+    config.pwa?.installTitle === undefined
+      ? {}
+      : { installTitle: config.pwa.installTitle },
+  );
+  const rootOf =
+    (plugins: ReadonlyArray<RootPlugin>) => (options: RootOptions) =>
+      webRoot({ title: config.title, theme, plugins, ...options });
+
+  if (config.auth === undefined) {
+    const app = assemble(parts as never) as unknown as PublicApp<A, C>;
+    return { ...app, theme, root: rootOf([pwa]) };
+  }
+
+  const { auth } = config;
+  const app = assemble({
+    ...(parts as object),
+    host,
+    auth: auth.session === undefined ? {} : { session: auth.session },
+  } as never) as AuthApp<A, S, C>;
+
+  // Asks who signs in to the device Backend, wherever the app is.
+  const named: RootPlugin = {
+    Provider: (props: { readonly children: ReactNode }) => {
+      const { asking, answer } = app.useGate().namedSignIn;
+      return (
+        <>
+          {props.children}
+          <LocalSignIn
+            open={asking}
+            presets={auth.presets ?? []}
+            onChoose={answer}
+            onCancel={() => answer(null)}
+          />
+        </>
+      );
+    },
+  };
+
+  /** The screen for whatever stands before an open Account. */
+  function GateFallback(props: { readonly view: NotOpen<S> }) {
+    const gate = app.useGate();
+    const { theme: shown } = theme.useTheme();
+    const notice = gate.notice;
+    const view = props.view as NotOpen<unknown>;
+    if (view.kind === 'accountLost')
+      return (
+        <AccountLost
+          lost={view.account.user}
+          others={view.accounts.map(({ user }) => user)}
+          onSignInAgain={() => void gate.signIn()}
+          onSwitch={gate.switchTo}
+          onSignOut={() => void gate.signOut()}
+        />
+      );
+    return (
+      <GateScreens
+        title={config.title}
+        {...(config.description !== undefined && {
+          description: config.description,
+        })}
+        mark={config.mark}
+        statusBar={<theme.StatusBar />}
+        theme={shown}
+        screen={screenOf(view)}
+        backend={gate.backend}
+        hasDevice={config.device !== undefined}
+        loginError={
+          notice?.kind === 'loginError'
+            ? (notice.error.description ?? 'Sign in didn’t finish. Try again.')
+            : null
+        }
+        onLoginErrorShown={gate.dismissNotice}
+        onSignIn={gate.signIn}
+        onCheckAgain={gate.checkAgain}
+        onRetry={gate.retry}
+        onSignOut={() => void gate.signOut()}
+        onBackend={(backend) => void gate.setBackend(backend)}
+      />
+    );
+  }
+
+  /**
+   * Renders `children` while an Account is open, and otherwise the screen
+   * for where sign-in stands, unless `fallback` says otherwise.
+   * Everything inside remounts on an Account Switch, so wrap as little as
+   * the part that needs an Account.
+   */
+  function SignedIn(props: {
+    readonly children: ReactNode;
+    readonly fallback?: ReactNode | ((view: NotOpen<S>) => ReactNode);
+  }) {
+    return (
+      <app.SignedIn
+        fallback={props.fallback ?? ((view) => <GateFallback view={view} />)}
+      >
+        {props.children}
+      </app.SignedIn>
+    );
+  }
+
+  return {
+    ...app,
+    SignedIn,
+    theme,
+    root: rootOf(config.device === undefined ? [pwa] : [pwa, named]),
+  };
+}
+
+/** A web app with Accounts, as `createApp` makes it. */
+export type WebAuthApp<A extends Apis, S, C> = AuthApp<A, S, C> & {
+  readonly theme: ReturnType<typeof createTheme>;
+  /** The root route: pass it to `createRootRoute`. */
+  readonly root: (options: RootOptions) => ReturnType<typeof webRoot>;
+};
+
+/** A web app with no Accounts, as `createApp` makes it. */
+export type WebPublicApp<A extends Apis, C> = PublicApp<A, C> & {
+  readonly theme: ReturnType<typeof createTheme>;
+  readonly root: (options: RootOptions) => ReturnType<typeof webRoot>;
+};

package/src/app/assemble/assemble.tsx

@@ -0,0 +1,339 @@
+import { Context, Effect, Layer } from 'effect';
+import type { RpcClient } from 'effect/rpc';
+import { type ReactNode, useSyncExternalStore } from 'react';
+import {
+  namedAccountsTable,
+  signIn,
+  type SignIn,
+} from '@kestack/auth-toolkit/client';
+import { Sync, type SyncStore } from '@kestack/std-toolkit/sync';
+import {
+  type ApiClients,
+  type Apis,
+  cloudProtocol,
+  type DeviceBackends,
+  deviceProtocol,
+} from '../apis/index.ts';
+import { createGate, gateReact, type GateView } from '../gate/index.ts';
+import type { Backend, Host, Storage } from '../host/index.ts';
+import {
+  defineSession,
+  keepSyncs,
+  type Opened,
+  OpenSessionProvider,
+  openSession,
+  type SessionDef,
+  useOpenedOrNone,
+} from '../session/index.ts';
+import { publicClients } from './public.ts';
+
+/** What an app with auth gives: what one Account keeps while it is
+ * active. Without a Session, `SignedIn` still works and every API is still
+ * signed; there is just nothing of the app's own to keep. */
+export interface AuthConfig<A extends Apis, S> {
+  readonly session?: SessionDef<A, S>;
+}
+
+/** What an app gives `createApp`, each part switching on only what needs
+ * it. */
+export interface AppConfig<A extends Apis, S, C> {
+  /** Where the app runs, made the first time anything asks. */
+  readonly host: () => Host;
+  /** The app's APIs, by name. */
+  readonly apis?: A;
+  /** The device Backend: every API's handlers, run in the app on the
+   * device's own Storage, or what loads them the first time it is chosen.
+   * Without it, the app has only the cloud Backend. */
+  readonly device?: (
+    storage: Storage,
+  ) => DeviceBackends<A> | Promise<DeviceBackends<A>>;
+  /** Signing in: several Accounts on this device, one open at a time, each
+   * with its own Session. Without it, the app has no Accounts. */
+  readonly auth?: AuthConfig<A, S>;
+  /** What only this device keeps and belongs to no user, such as Settings,
+   * opened on first use. */
+  readonly cache?: (storage: Storage) => C;
+}
+
+type NotOpen<S> = Exclude<GateView<S>, { kind: 'open' }>;
+
+/** What runs while the app is on one Backend: how a Session reaches each
+ * API, where its Std Sync is kept, and what deletes signed-out users'. */
+class Link extends Context.Service<
+  Link,
+  {
+    /** Each API's protocol for an Account whose token `token` gives. */
+    readonly protocols: (
+      token: Effect.Effect<string>,
+    ) => Readonly<Record<string, Layer.Layer<RpcClient.Protocol>>>;
+    readonly store: SyncStore;
+    readonly keep: (userIds: ReadonlyArray<string>) => Effect.Effect<void>;
+  }
+>()('@kestack/web-platform/app/Link') {}
+
+/** An app's parts with no Accounts: its APIs and its cache. */
+const makeCore = <A extends Apis, C>(
+  config: Pick<AppConfig<A, unknown, C>, 'host' | 'apis' | 'device' | 'cache'>,
+) => {
+  let made: Host | undefined;
+  const host = () => (made ??= config.host());
+  const apis = (config.apis ?? {}) as A;
+  const names = Object.keys(apis);
+
+  let loaded: Promise<DeviceBackends<A>> | undefined;
+  const loadDevice = () =>
+    (loaded ??= Promise.resolve(config.device!(host().storage)));
+
+  const cloudProtocols = (token: Effect.Effect<string> | null = null) =>
+    Object.fromEntries(
+      names.map((name) => [
+        name,
+        cloudProtocol(apis[name]!, host().cloud.url, token),
+      ]),
+    );
+  const deviceProtocols = async () => {
+    const handlers = await loadDevice();
+    return Object.fromEntries(
+      names.map((name) => [
+        name,
+        deviceProtocol(apis[name]!, handlers[name] as never),
+      ]),
+    );
+  };
+  const protocolOf = async (backend: Backend, name: string) =>
+    backend === 'device'
+      ? (await deviceProtocols())[name]!
+      : cloudProtocols()[name]!;
+
+  let cacheMade: C | undefined;
+  const cache = () => (cacheMade ??= config.cache!(host().storage));
+
+  return {
+    host,
+    apis,
+    hasDevice: config.device !== undefined,
+    cloudProtocols,
+    deviceProtocols,
+    protocolOf,
+    cache,
+  };
+};
+
+/** The Backend an app with no Accounts runs on: the one its launch asked
+ * for, else the cloud, and changed by hand. */
+const backendStore = (core: ReturnType<typeof makeCore>) => {
+  let backend: Backend | null = null;
+  const listeners = new Set<() => void>();
+  const current = (): Backend => {
+    if (backend === null) {
+      const asked = core.host().lifecycle.launchBackend();
+      backend = asked === 'device' && core.hasDevice ? 'device' : 'cloud';
+    }
+    return backend;
+  };
+  return {
+    current,
+    subscribe: (changed: () => void) => {
+      listeners.add(changed);
+      return () => void listeners.delete(changed);
+    },
+    set: (next: Backend) => {
+      backend = next === 'device' && core.hasDevice ? 'device' : 'cloud';
+      listeners.forEach((changed) => changed());
+    },
+  };
+};
+
+/**
+ * An app on any platform. Nothing runs until a screen first asks, so it
+ * can be made where the Host is not there yet, as on a web server. With
+ * `auth`, it runs sign-in on this device on the cloud or the device
+ * Backend, and opens one Session per active Account, with every API signed
+ * as them and a Std Sync named for them; the app's Session says what that
+ * Session holds, this says when. Make one per app. The Web Platform's
+ * `createApp` calls it with the browser's Host; tests call it with one in
+ * memory.
+ */
+export function createApp<A extends Apis, S, C = never>(
+  config: AppConfig<A, S, C> & { readonly auth: AuthConfig<A, S> },
+): AuthApp<A, S, C>;
+export function createApp<A extends Apis, C = never>(
+  config: AppConfig<A, never, C> & { readonly auth?: undefined },
+): PublicApp<A, C>;
+export function createApp<A extends Apis, S, C>(
+  config: AppConfig<A, S, C>,
+): AuthApp<A, S, C> | PublicApp<A, C> {
+  const core = makeCore(config);
+  return config.auth === undefined
+    ? publicApp(core)
+    : authApp(core, config.auth);
+}
+
+const publicApp = <A extends Apis, C>(
+  core: ReturnType<typeof makeCore<A, C>>,
+) => {
+  const backend = backendStore(core);
+  const publics = publicClients(core.apis, {
+    backend: backend.current,
+    protocol: core.protocolOf,
+  });
+  return {
+    /** Where the app runs. */
+    host: core.host,
+    /** This device's cache, opened on first use. */
+    cache: core.cache,
+    /** One API's client. */
+    useApi: <K extends keyof A & string>(name: K): ApiClients<A>[K] =>
+      publics[name],
+    /** The Backend the app runs on, and changing it. */
+    useBackend: () => ({
+      backend: useSyncExternalStore(
+        backend.subscribe,
+        backend.current,
+        () => 'cloud' as const,
+      ),
+      setBackend: backend.set,
+    }),
+  };
+};
+
+/** An app with no Accounts, as `createApp` makes it. */
+export type PublicApp<A extends Apis, C> = ReturnType<typeof publicApp<A, C>>;
+
+const authApp = <A extends Apis, S, C>(
+  core: ReturnType<typeof makeCore<A, C>>,
+  auth: AuthConfig<A, S>,
+) => {
+  const { host, apis } = core;
+  const session =
+    auth.session ??
+    (defineSession(apis, () => Effect.void) as unknown as SessionDef<A, S>);
+
+  const gate = createGate<Opened<S>, Link>({
+    host,
+    cloud: () => {
+      const cloudSignIn = host().cloud.signIn;
+      if (cloudSignIn === undefined)
+        throw new Error('An app with auth needs a Host that signs in');
+      return Layer.mergeAll(
+        cloudSignIn,
+        Layer.sync(Link, () => ({
+          protocols: (token) => core.cloudProtocols(token),
+          store: host().storage.sync,
+          keep: (userIds) =>
+            Effect.tryPromise(() =>
+              keepSyncs(userIds, host().storage.sync),
+            ).pipe(
+              Effect.catch((error) => Effect.logWarning('[syncs]', error)),
+              Effect.asVoid,
+            ),
+        })),
+      ) as Layer.Layer<SignIn | Link>;
+    },
+    ...(core.hasDevice && {
+      device: async (choose) => {
+        const protocols = await core.deviceProtocols();
+        return Layer.mergeAll(
+          signIn.named({
+            choose,
+            storage: host().storage.table(namedAccountsTable, 'device'),
+          }),
+          Layer.succeed(Link, {
+            protocols: () => protocols,
+            // The device Backend keeps everything already: a Session's Std
+            // Sync lives in memory, and there is nothing to delete.
+            store: Sync.memory(),
+            keep: () => Effect.void,
+          }),
+        );
+      },
+    }),
+    session: (account, token, status) =>
+      Effect.gen(function* () {
+        const { protocols, store } = yield* Link;
+        return yield* openSession({
+          apis,
+          protocols: protocols(token) as never,
+          store,
+          account,
+          token,
+          status,
+          open: session.open,
+          service: session.Service,
+        });
+      }),
+    keep: (userIds) => Link.use((link) => link.keep(userIds)),
+  });
+  const react = gateReact(gate);
+  const publics = publicClients(apis, {
+    backend: () => gate.backend() ?? 'cloud',
+    protocol: core.protocolOf,
+  });
+
+  // Gives the open Session to everything under SignedIn.
+  function Provide(props: { readonly children: ReactNode }) {
+    return (
+      <OpenSessionProvider opened={react.useSession() as Opened<unknown>}>
+        {props.children}
+      </OpenSessionProvider>
+    );
+  }
+
+  /**
+   * Renders `children` while an Account is open, `fallback` otherwise (a
+   * node, or one per view). Everything inside remounts on an Account
+   * Switch, so wrap as little as the part that needs an Account.
+   */
+  function SignedIn(props: {
+    readonly children: ReactNode;
+    readonly fallback?: ReactNode | ((view: NotOpen<S>) => ReactNode);
+  }) {
+    return (
+      <react.SignedIn
+        fallback={
+          props.fallback as
+            | ReactNode
+            | ((view: NotOpen<Opened<S>>) => ReactNode)
+        }
+      >
+        <Provide>{props.children}</Provide>
+      </react.SignedIn>
+    );
+  }
+
+  return {
+    /** Where the app runs. */
+    host,
+    /** The Gate itself, outside React: for tests and non-React code. */
+    gate,
+    /** This device's cache, opened on first use. */
+    cache: core.cache,
+    SignedIn,
+    SignedOut: react.SignedOut,
+    /** The Gate, anywhere: what it shows, the Backend, online, signing in. */
+    useGate: react.useGate,
+    /** The Accounts signed in, what is done with them, and `manage`: the
+     * sign-in service's page for them. Only inside `SignedIn`. */
+    useAccounts: () => ({
+      ...react.useAccounts(),
+      manage: () => host().cloud.manageAccounts?.() ?? Promise.resolve(),
+    }),
+    /** The open Session's value; only inside `SignedIn`. */
+    useSession: session.use,
+    /** Runs an Effect in the open Session; only inside `SignedIn`. */
+    useRun: session.useRun,
+    /** Whether the open Account has been confirmed, live. */
+    useStatus: session.useStatus,
+    /** One API's client: signed as the open Account inside `SignedIn`, and
+     * as nobody outside it, where only a public call goes out. */
+    useApi: <K extends keyof A & string>(name: K): ApiClients<A>[K] => {
+      const opened = useOpenedOrNone();
+      return (opened?.apis[name] ?? publics[name]) as ApiClients<A>[K];
+    },
+    /** The open Session, for Effect code: `yield* app.Session`. */
+    Session: session.Service,
+  };
+};
+
+/** An app with Accounts, as `createApp` makes it. */
+export type AuthApp<A extends Apis, S, C> = ReturnType<typeof authApp<A, S, C>>;

package/src/app/assemble/index.ts

@@ -0,0 +1,7 @@
+export {
+  type AppConfig,
+  type AuthApp,
+  type AuthConfig,
+  createApp,
+  type PublicApp,
+} from './assemble.tsx';

package/src/app/assemble/public.ts

@@ -0,0 +1,98 @@
+import {
+  Context,
+  Effect,
+  Layer,
+  ManagedRuntime,
+  type Schema,
+  Stream,
+} from 'effect';
+import { type RpcClient, RpcClient as Client, RpcSchema } from 'effect/rpc';
+import { Authz } from '@kestack/auth-toolkit/guard';
+import type { ApiClients, Apis } from '../apis/index.ts';
+import type { Backend } from '../host/index.ts';
+
+interface PublicClient {
+  readonly '@kestack/web-platform/PublicClient': unique symbol;
+}
+
+type AnyCall = (...args: ReadonlyArray<unknown>) => unknown;
+
+/**
+ * Every API's client signed as nobody, on whichever Backend runs when a
+ * call is made: a public call goes out as it is, and a guarded one fails
+ * Unauthenticated without being sent. For calls outside `SignedIn`.
+ */
+export const publicClients = <A extends Apis>(
+  apis: A,
+  options: {
+    readonly backend: () => Backend;
+    readonly protocol: (
+      backend: Backend,
+      name: string,
+    ) => Promise<Layer.Layer<RpcClient.Protocol>>;
+  },
+): ApiClients<A> => {
+  // One client per Backend and API, made on its first call.
+  const made = new Map<string, Promise<Record<string, AnyCall>>>();
+  const clientOf = (name: string) => {
+    const backend = options.backend();
+    const key = `${backend}/${name}`;
+    let client = made.get(key);
+    if (client === undefined) {
+      client = options.protocol(backend, name).then((protocol) => {
+        const Key = Context.Service<PublicClient, Record<string, AnyCall>>(
+          `@kestack/web-platform/PublicClient/${key}`,
+        );
+        const runtime = ManagedRuntime.make(
+          Layer.effect(
+            Key,
+            Client.make(apis[name]!.group) as unknown as Effect.Effect<
+              Record<string, AnyCall>
+            >,
+          ).pipe(Layer.provide([protocol, Authz.bearer(() => null)])),
+        );
+        return runtime.runPromise(
+          Effect.gen(function* () {
+            return yield* Key;
+          }),
+        );
+      });
+      made.set(key, client);
+      // A load that failed is tried again on the next call.
+      client.catch(() => {
+        if (made.get(key) === client) made.delete(key);
+      });
+    }
+    return client;
+  };
+
+  return Object.fromEntries(
+    Object.entries(apis).map(([name, { group }]) => {
+      const calls = Object.fromEntries(
+        [...group.requests.values()].map((rpc) => {
+          const client = Effect.promise(() => clientOf(name));
+          const call = RpcSchema.isStreamSchema(
+            (rpc as unknown as { readonly successSchema: Schema.Top })
+              .successSchema,
+          )
+            ? (...args: ReadonlyArray<unknown>) =>
+                Stream.unwrap(
+                  Effect.map(
+                    client,
+                    (made) =>
+                      made[rpc._tag]!(...args) as Stream.Stream<unknown>,
+                  ),
+                )
+            : (...args: ReadonlyArray<unknown>) =>
+                Effect.flatMap(
+                  client,
+                  (made) =>
+                    made[rpc._tag]!(...args) as Effect.Effect<unknown, unknown>,
+                );
+          return [rpc._tag, call];
+        }),
+      );
+      return [name, calls];
+    }),
+  ) as unknown as ApiClients<A>;
+};