lecodes-sdk 2.2.13 → 2.2.14

package/src/runtime/rpc.ts

@@ -8,7 +8,8 @@
  *   export const db        = __serverOnly("schema.server.ts#db")
  *
  * Wire (implemented by the runner):
- *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known,
+ *                               `x-lecodes-push: <address>` once the device registered for notifications
  *                               — with a `File` among the arguments: multipart, the field `args` is
  *                               that JSON with `{"$file": <i>}` where the file stood, `file<i>` the files
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
@@ -24,6 +25,7 @@ import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
 import type { ChannelSubscription } from "../server/channel"
+import { _pushRuntime } from "./pushSeam"
 
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
@@ -69,6 +71,9 @@ export const __rpc = (serverUrl: string, id: string) => {
     const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
+    // the device's push address, for the session to carry (src/server/auth/host.ts) — what a push channel reaches the user by
+    const pushAddress = _pushRuntime.current?.address()
+    if (pushAddress) headers["x-lecodes-push"] = pushAddress
     // a File anywhere among the arguments leaves its place to a marker and travels beside them
     const files: File[] = []
     const json = JSON.stringify({ args }, (_key, value) => value instanceof File ? { $file: files.push(value) - 1 } : value)
@@ -88,6 +93,8 @@ export const __rpc = (serverUrl: string, id: string) => {
     let body: any
     try { body = res.json() } catch { body = null }
     if (body && typeof body === "object" && "session" in body) setSession(serverUrl, body.session ?? null)
+    // the server asks this device to register for notifications: a signed-in session without an address, and push channels to hear
+    if (body && typeof body === "object" && body.push === true) _pushRuntime.current?.requestRegister()
     if (body && body.ok === true) return body.result
     if (body && body.ok === false) throw new RpcError(body.status ?? res.status, body.message ?? "")
     throw new RpcError(res.status, `Endpoint ${id}: unexpected response (HTTP ${res.status})`)
@@ -287,3 +294,30 @@ export const __channel = (serverUrl: string, id: string) => ({
     throw new RpcError(0, `Channel ${id}: the server publishes, the app subscribes — call a server function that publishes`)
   },
 })
+
+// ───────────────────────────── push channels ─────────────────────────────
+
+/**
+ * Build the client proxy of push channel `id` — what a `pushChannel()` export of a `*.server.ts` file is
+ * in the app (its type is the server's: src/server/pushChannel.ts). The notifications come off the push
+ * plugin, through the runtime its wrapper installed (`__pushEnable()`, the first line of the stubs of a
+ * project with push channels — ./pushSeam.ts): `onTap` hears this channel's taps (the one that started
+ * the app included), `onMessage` its arrivals while the app is in the foreground. On a host without the
+ * plugin a handler is recorded and never called, like the plugin's own listeners.
+ */
+export const __pushChannel = (serverUrl: string, id: string) => {
+  const listen = (kind: "tap" | "message", handler: unknown): ChannelSubscription => {
+    if (typeof handler !== "function") throw new RpcError(0, `Push channel ${id}: ${kind === "tap" ? "onTap" : "onMessage"}(handler) — no handler given`)
+    const runtime = _pushRuntime.current
+    if (!runtime) throw new RpcError(0, `Push channel ${id}: the push runtime is not installed — the compiler puts __pushEnable() in the stub of a project with push channels`)
+    const off = runtime.on(kind, id, handler as (payload: unknown) => void)
+    return { close: off }
+  }
+  return {
+    onTap: (handler: unknown): ChannelSubscription => listen("tap", handler),
+    onMessage: (handler: unknown): ChannelSubscription => listen("message", handler),
+    send(): never {
+      throw new RpcError(0, `Push channel ${id}: the server sends, the app listens — call a server function that sends${serverUrl ? "" : " (and compile with serverUrl)"}`)
+    },
+  }
+}

package/src/server/auth/host.ts

@@ -12,7 +12,13 @@
  *
  * Tokens: 32 random bytes (base64url) held by the client transport; only `sha256(token)` is stored.
  * A request without a valid token gets a fresh guest session and the token travels back in the
- * envelope (`session`); sign-in/out ROTATE the token the same way.
+ * envelope (`session`); sign-in/out ROTATE the token the same way (the row stays: what it holds of the
+ * device — its push address — survives a sign-out, and a sign-in on the same device finds it there).
+ *
+ * The push address: the transport sends the device's address at the platform's push relay in the
+ * `x-lecodes-push` header of every call (once the device registered); `resolve` keeps the session's
+ * `pushAddress` equal to it. That is the whole binding of a device to a user — a push channel's `send`
+ * reaches a user through the live sessions that carry an address (../push/host.ts).
  *
  * Identities: every sign-in method is an `Identity` row `(provider, subject)` of a user — `email:<address>`
  * or `login:<name>` (its `hash` = the password). The one rule that keeps passwords honest: proving an
@@ -114,6 +120,17 @@ const parseLogin = (login: unknown): { provider: "email" | "login", subject: str
 
 const identityKey = (provider: IdentityProvider, subject: string) => `${provider}:${subject}`
 
+/** The header the transport tells the device's push address in (src/runtime/rpc.ts). */
+export const PUSH_ADDRESS_HEADER = "x-lecodes-push"
+const PUSH_ADDRESS_RE = /^[A-Za-z0-9_-]{1,128}$/
+/** The address of this request's device, when the header carries a well-formed one. */
+const pushAddressOf = (ctx: RequestContext): string | null => {
+  const headers = ctx.headers ?? {}
+  const raw = headers[PUSH_ADDRESS_HEADER] ?? Object.entries(headers).find(([k]) => k.toLowerCase() === PUSH_ADDRESS_HEADER)?.[1]
+  const value = typeof raw === "string" ? raw.trim() : ""
+  return PUSH_ADDRESS_RE.test(value) ? value : null
+}
+
 /** A sliding-window counter per key (in-worker; the persistent limits live on the rows). */
 const window = (map: Map<string, number[]>, key: string, now: number, span: number): number[] => {
   const list = (map.get(key) ?? []).filter(x => now - x < span)
@@ -146,7 +163,7 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
   const log = cfg.log ?? ((level, text) => (level === "warn" ? console.warn(text) : console.info(text)))
 
   // token → session (60 s). Cleared on every mutation — correctness over reuse.
-  const sessionCache = new Map<string, { sessionId: number, userId: number | null, at: number }>()
+  const sessionCache = new Map<string, { sessionId: number, userId: number | null, pushAddress: string | null, at: number }>()
   const clearCache = () => { sessionCache.clear() }
 
   const requireAuth = () => {
@@ -165,9 +182,10 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
 
   const mint = async (ctx: RequestContext): Promise<AuthState> => {
     const token = randomToken()
-    const { id } = await sessions.insert({ tokenHash: await sha256(token) })
-    const state: AuthState = { sessionId: id, userId: null, issuedToken: token }
-    sessionCache.set(token, { sessionId: id, userId: null, at: now() })
+    const pushAddress = pushAddressOf(ctx)
+    const { id } = await sessions.insert({ tokenHash: await sha256(token), ...(pushAddress ? { pushAddress } : {}) })
+    const state: AuthState = { sessionId: id, userId: null, pushAddress, issuedToken: token }
+    sessionCache.set(token, { sessionId: id, userId: null, pushAddress, at: now() })
     ctx.auth = state
     ctx.sessionToken = token
     return state
@@ -188,21 +206,34 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
     if (opts.rotate) await rotate(ctx)
   }
 
+  /** The session's push address follows the header: written when it differs (a registration, a new address
+   *  after the OS rotated the token) — never cleared by a call without the header: the app may not have
+   *  asked the plugin yet in this run. */
+  const followPushAddress = async (token: string, sessionId: number, held: string | null, told: string | null): Promise<string | null> => {
+    if (!told || told === held) return held
+    await sessions.update(sessionId, { pushAddress: told })
+    const c = sessionCache.get(token)
+    if (c) c.pushAddress = told
+    return told
+  }
+
   const resolve = async (ctx: RequestContext): Promise<void> => {
     if (!tables) return
     const token = ctx.sessionToken
     if (token) {
       const c = sessionCache.get(token)
       if (c && now() - c.at < CACHE_TTL_MS) {
-        ctx.auth = { sessionId: c.sessionId, userId: c.userId }
+        const pushAddress = await followPushAddress(token, c.sessionId, c.pushAddress, pushAddressOf(ctx))
+        ctx.auth = { sessionId: c.sessionId, userId: c.userId, pushAddress }
         return
       }
-      const row = await sessions.where({ tokenHash: await sha256(token) }).select({ id: true, revoked: true, lastSeenAt: true, user: { id: true } }).first()
+      const row = await sessions.where({ tokenHash: await sha256(token) }).select({ id: true, revoked: true, lastSeenAt: true, pushAddress: true, user: { id: true } }).first()
       if (row && !row.revoked) {
         const userId: number | null = row.user ? row.user.id : null
         if (now() - (row.lastSeenAt ?? 0) > SEEN_UPDATE_MS) sessions.update(row.id, { lastSeenAt: now() }).then(undefined, () => {})
-        sessionCache.set(token, { sessionId: row.id, userId, at: now() })
-        ctx.auth = { sessionId: row.id, userId }
+        sessionCache.set(token, { sessionId: row.id, userId, pushAddress: row.pushAddress ?? null, at: now() })
+        const pushAddress = await followPushAddress(token, row.id, row.pushAddress ?? null, pushAddressOf(ctx))
+        ctx.auth = { sessionId: row.id, userId, pushAddress }
         return
       }
     }

package/src/server/auth/models.ts

@@ -1,7 +1,8 @@
 /**
  * The two models sign-in adds to a database — `defineDb({...}).withAuth({ model: "User" })`:
  *
- *   Session   one device: the hash of its token, and the user it is signed in as (none = a guest)
+ *   Session   one device: the hash of its token, the user it is signed in as (none = a guest), and the
+ *             device's push address when it told one (what a push channel's `send` reaches the user by)
  *   Identity  one way a user signs in: `email:<address>` or `login:<name>` (with the password's hash
  *             when one is set) — several per user.
  *
@@ -40,6 +41,9 @@ export const sessionFields = (userModel: string) => ({
   codeHash:     t.string().optional(),
   codeExpires:  t.date().optional(),
   codeAttempts: t.int().default(0),
+  /** The device's address at the platform's push relay (`x-lecodes-push` of its calls) — the session's own
+   *  secret, like the token: never read back by a project (../push/host.ts sends by it). */
+  pushAddress:  t.string().optional(),
   user:         t.one(userModel).optional().onDelete("cascade"),
 })
 

package/src/server/auth/types.ts

@@ -13,6 +13,8 @@ import type { RequestContext } from "../context"
 export type AuthState = {
   sessionId: number
   userId: number | null
+  /** The push address of the device, as the session holds it after this request's header was read (null = none). */
+  pushAddress?: string | null
   /** A token to hand back to the client in this response (a new guest session, or a rotation). */
   issuedToken?: string
 }

package/src/server/host.ts

@@ -21,6 +21,9 @@ export type { ServerManifest, ServerExport } from "../compile/serverSplit"
 export { validateArgs, ValidationError } from "./validate"
 export type { ParamSchema, Schema as ParamSchemaNode } from "./validate"
 export { createAuthHost, sha256, hashPassword, verifyPassword } from "./auth/host"
+export { createPushHost, PUSH_BATCH } from "./push/host"
+export type { PushHost, PushHostConfig, PushRelay, PushRelayMessage, PushRelayResult } from "./push/host"
+export type { PushSender } from "./pushChannel"
 export type { AuthHost, AuthHostConfig, AuthMail } from "./auth/host"
 export type { AuthState, AuthOps } from "./auth/types"
 export type { AppConfig } from "./auth/appConfig"
@@ -52,6 +55,8 @@ export type ServerDescription = {
   models: Record<string, { fields: Record<string, FieldDescription>, auth?: true, files?: true }>
   endpoints: { id: string, params: unknown[] | null }[]
   channels: string[]
+  /** The push channels (`pushChannel()` exports), by id. */
+  pushChannels: string[]
   /** The project's model of a user (`null` = its db has no sign-in). */
   auth: { model: string | null }
   /** `app.json` name (when the compile embedded one). */
@@ -99,6 +104,7 @@ export const describeServer = (server: LoadedServer): ServerDescription => {
     models,
     endpoints: [...server.endpoints.keys()].map(id => ({ id, params: params[id] ?? null })),
     channels: [...server.channels.keys()],
+    pushChannels: [...server.pushChannels.keys()],
     auth: { model: db?.$auth?.model ?? null },
     appName: server.manifest.app?.name,
   }

package/src/server/inject.ts

@@ -3,13 +3,14 @@
  * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
  * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
  *
- * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, request. Sign-in is not a
- * global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`.
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, pushChannel, request. Sign-in is
+ * not a global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`.
  */
 
 export { t, model, defineDb, ref } from "./db"
 export { ApiError } from "./errors"
 export { channel } from "./channel"
+export { pushChannel, type PushChannel, type PushMessage, type PushNotification, type PushTarget } from "./pushChannel"
 export { request } from "./context"
 export type { StoredFile, StoredImage } from "./files/models"
 /** The value an SVG source is to the client (`assetIcon(…)` compiles to `SvgSource(…)`): a shared module of

package/src/server/push/host.ts

@@ -0,0 +1,143 @@
+/**
+ * The HOST side of push channels (../pushChannel.ts): what `send` does, run where the runner imports
+ * `sdk/server` (the project worker, the CLI's local backend) over the sessions of the db with sign-in.
+ *
+ *   createPushHost({ db, relay }).install()        // the bundle's `send` reaches it through globalThis.__lecodesPushSend
+ *
+ * A user's devices are their sessions: each carries the address its device told the transport
+ * (`Session.pushAddress`, written by the auth host from the `x-lecodes-push` header). `send` takes the
+ * live sessions of the users, their addresses once each, and hands them to the RELAY — the host's
+ * road to the platform's sender (the runner: the platform's internal route under its shared secret;
+ * `lecodes dev`: the developer's own login) — in batches of what the platform takes per request. The
+ * relay answers what did not go: an address the platform knows no more (`unknown`: the device
+ * unregistered, a registration row gone) or has disabled (reason "disabled") is a dead one, and is
+ * dropped from its session so it is not tried again; any other failure (the platform's credentials, a
+ * provider's hiccup) leaves the address where it is.
+ *
+ * A host with no relay sends nothing and says so once per channel in the server console — a check, a
+ * run without a login — and `send` answers 0: a notification with nowhere to go is not the app's bug.
+ */
+
+import type { AuthBinding } from "../db/types"
+import { setPushSender, type PushMessage } from "../pushChannel"
+
+/** What goes to the platform for one batch of addresses. */
+export type PushRelayMessage = {
+  /** The push channel's id (`<path>#<export>`): the app's side hears each channel's own. */
+  channel: string
+  title: string
+  body?: string
+  url?: string
+  data?: Record<string, unknown>
+  badge?: number
+}
+export type PushRelayResult = {
+  /** How many devices the platform sent to. */
+  sent: number
+  /** What it could not send to, by address: "disabled" = the platform has given the device up. */
+  failed: { address: string, reason: string }[]
+  /** Addresses the platform does not know (the whole batch was refused for them): the host drops them
+   *  from their sessions and sends the rest again. */
+  unknown?: string[]
+}
+/** The host's road to the platform's sender, for up to `PUSH_BATCH` addresses at a time. */
+export type PushRelay = (to: string[], message: PushRelayMessage) => Promise<PushRelayResult>
+
+export type PushHostConfig = {
+  /** The project's db with sign-in (its sessions are the devices); `null`, or a db without it = `send` fails: there are no devices. */
+  db: { readonly $auth: AuthBinding | null } | null
+  /** Absent = this host sends nothing (`send` answers 0 and warns). */
+  relay?: PushRelay | null
+  /** Server console sink (default console). */
+  log?: (level: "warn" | "info", text: string) => void
+}
+
+export type PushHost = {
+  /** Is there a relay? Without one `send` answers 0. */
+  readonly enabled: boolean
+  /** Install `send` for the bundle's push channels (`globalThis.__lecodesPushSend`). */
+  install(): void
+  send(channelId: string, userIds: number[], message: PushMessage<any>): Promise<{ sent: number }>
+}
+
+/** What the platform takes per request. */
+export const PUSH_BATCH = 500
+
+const chunks = <T>(list: T[], size: number): T[][] => {
+  const out: T[][] = []
+  for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size))
+  return out
+}
+
+export const createPushHost = (cfg: PushHostConfig): PushHost => {
+  const sessions = cfg.db?.$auth?.session ?? null
+  const relay = cfg.relay ?? null
+  const log = cfg.log ?? ((level, text) => (level === "warn" ? console.warn(text) : console.info(text)))
+  const warned = new Set<string>()
+
+  type Row = { id: number, pushAddress: string | null }
+  /** The live sessions of these users that have a device, by address (one session per address — the latest). */
+  const devices = async (userIds: number[]): Promise<Map<string, number[]>> => {
+    const rows: Row[] = await sessions.where({ user: { id: { $in: userIds } }, revoked: false }).select({ id: true, pushAddress: true })
+    const byAddress = new Map<string, number[]>()
+    for (const row of rows) {
+      if (!row.pushAddress) continue
+      const list = byAddress.get(row.pushAddress) ?? []
+      list.push(row.id)
+      byAddress.set(row.pushAddress, list)
+    }
+    return byAddress
+  }
+  /** A dead address: no session keeps it. */
+  const forget = async (byAddress: Map<string, number[]>, addresses: string[]): Promise<void> => {
+    const ids = addresses.flatMap(a => byAddress.get(a) ?? [])
+    if (!ids.length) return
+    await sessions.where({ id: { $in: ids } }).updateMany({ pushAddress: null })
+  }
+
+  const send = async (channelId: string, userIds: number[], message: PushMessage<any>): Promise<{ sent: number }> => {
+    if (!sessions) {
+      throw new Error("pushChannel.send: the project's database has no sign-in — a user's devices are the sessions of defineDb({...}).withAuth({ model }), without it there is no one to send to")
+    }
+    if (!relay) {
+      if (!warned.has(channelId)) {
+        warned.add(channelId)
+        log("warn", `${channelId}: notifications are not sent from this backend (no road to the platform's sender) — a deployed backend sends them`)
+      }
+      return { sent: 0 }
+    }
+    const byAddress = await devices(userIds)
+    if (byAddress.size === 0) return { sent: 0 }
+    const wire: PushRelayMessage = {
+      channel: channelId,
+      title: message.title,
+      ...(message.body !== undefined ? { body: message.body } : {}),
+      ...(message.url !== undefined ? { url: message.url } : {}),
+      ...(message.data !== undefined ? { data: message.data as Record<string, unknown> } : {}),
+      ...(message.badge !== undefined ? { badge: message.badge } : {}),
+    }
+    let sent = 0
+    for (let batch of chunks([...byAddress.keys()], PUSH_BATCH)) {
+      let result = await relay(batch, wire)
+      // the platform knows none of these any more: drop them, and send to the rest
+      if (result.unknown?.length) {
+        const unknown = new Set(result.unknown)
+        await forget(byAddress, [...unknown])
+        batch = batch.filter(a => !unknown.has(a))
+        if (!batch.length) continue
+        result = await relay(batch, wire)
+        if (result.unknown?.length) await forget(byAddress, result.unknown)
+      }
+      sent += result.sent
+      const dead = result.failed.filter(f => f.reason === "disabled").map(f => f.address)
+      if (dead.length) await forget(byAddress, dead)
+    }
+    return { sent }
+  }
+
+  return {
+    get enabled() { return relay !== null },
+    install() { setPushSender(send) },
+    send,
+  }
+}

package/src/server/pushChannel.ts

@@ -0,0 +1,121 @@
+/**
+ * Push channels: the server's notifications to a person's devices — the twin of ./channel.ts for what
+ * reaches someone while the app is closed. One export types both sides:
+ *
+ *   export const orderShippedPushChannel = pushChannel<{ orderId: number }>()         // pushes.server.ts
+ *
+ *   await orderShippedPushChannel.send(order.owner, { title: "Order shipped", data: { orderId } })   // server
+ *
+ *   orderShippedPushChannel.onTap(({ data }) => Router.push(OrderScreen(data.orderId)))             // app
+ *   orderShippedPushChannel.onMessage(({ title }) => toast(title))
+ *
+ * `send` reaches every device the user is signed in on. The devices are the sessions of the project's db
+ * with sign-in (`defineDb(...).withAuth(...)`): a session carries the address of its device — the app's
+ * transport tells it with every call, and the server asks the device to register when a signed-in
+ * session has none (the first response after a sign-in; the OS asks the permission then) — and a
+ * sign-out leaves the device on a guest session, which no `send` reaches. A user with no device is zero
+ * sends, not an error. `send` needs no request: a timer may call it.
+ *
+ * The server holds no push key: the host sends through the platform (./push/host.ts), reached here over
+ * the `globalThis.__lecodesPushSend` seam (the compiled bundle carries its own SDK copy — ./context.ts).
+ * A channel's identity is its export (`<path>#<name>`), assigned when the bundle is loaded
+ * (`loadServerModules`), and it travels in the notification: the app's side hears each channel's own.
+ *
+ * In the app the export is another object — the proxy `__pushChannel` of src/runtime/rpc.ts — which is
+ * why `onTap` / `onMessage` here only throw.
+ */
+
+import type { ChannelSubscription } from "./channel"
+
+export type { ChannelSubscription }
+
+/** Whom a notification goes to: a user id, or a row that has one (`db.auth.requireUser().select({ id: true })`, a relation). */
+export type PushTarget = number | { id: number }
+
+/** What a notification shows, and what it carries for the app (`data`, the channel's type). */
+export type PushMessage<D> = {
+  /** Up to 200 characters. */
+  title: string
+  /** The second line, up to 1000 characters. */
+  body?: string
+  /** A link for the app to open on a tap (`onTap` gets it — it is not opened by itself). */
+  url?: string
+  /** The number on the app's icon (iOS; 0 clears it). */
+  badge?: number
+} & (undefined extends D ? { data?: D } : { data: D })
+
+/** A notification as the app receives it: what was sent, and the channel it came through. */
+export type PushNotification<D> = PushMessage<D> & { channel: string }
+
+export interface PushChannel<D extends Record<string, unknown> | undefined = undefined> {
+  /** Server: send `message` to every device `user` is signed in on (one id or several). Answers how many
+   *  devices it went to — none is 0, not an error. */
+  send(user: PushTarget | PushTarget[], message: PushMessage<D>): Promise<{ sent: number }>
+  /** App: a notification of this channel was tapped — while the app ran, or to start it. Lives until `close()`. */
+  onTap(handler: (notification: PushNotification<D>) => void): ChannelSubscription
+  /** App: a notification of this channel arrived while the app was in the foreground: the app shows it
+   *  (the host shows no banner); a channel without this handler gets the system banner. */
+  onMessage(handler: (notification: PushNotification<D>) => void): ChannelSubscription
+}
+
+/** What the host reads of a push channel (src/server/runtime.ts). */
+export type PushChannelRecord = {
+  /** set by the runtime: `<path>#<export>` */
+  __id: string | null
+  readonly __pushChannel: true
+}
+
+/** The host's sender (./push/host.ts): the channel, the users' ids, the message → how many devices. */
+export type PushSender = (channelId: string, userIds: number[], message: PushMessage<any>) => Promise<{ sent: number }>
+const seam = globalThis as unknown as { __lecodesPushSend?: PushSender }
+
+/** Host hook (runner / local backend / test harness): where `send` delivers to. */
+export const setPushSender = (sender: PushSender | null) => {
+  if (sender) seam.__lecodesPushSend = sender
+  else delete seam.__lecodesPushSend
+}
+
+const TITLE_MAX = 200
+
+/** The ids of `send`'s first argument, each once; throws on what is not a user. */
+export const pushTargetIds = (user: unknown): number[] => {
+  const list = Array.isArray(user) ? user : [user]
+  const ids = new Set<number>()
+  for (const u of list) {
+    const id = typeof u === "number" ? u : u && typeof u === "object" ? (u as { id?: unknown }).id : undefined
+    if (typeof id !== "number" || !Number.isInteger(id)) {
+      throw new Error(`pushChannel.send: a user is an id or a row with one ({ id }), got ${u === null ? "null" : Array.isArray(u) ? "an array" : typeof u}`)
+    }
+    ids.add(id)
+  }
+  return [...ids]
+}
+
+export const pushChannel = <D extends Record<string, unknown> | undefined = undefined>(): PushChannel<D> => {
+  const ch: PushChannelRecord & Record<string, unknown> = {
+    __id: null,
+    __pushChannel: true,
+    async send(user: unknown, message: PushMessage<any>) {
+      if (!ch.__id) throw new Error("pushChannel.send: the channel is not registered — export it from a *.server.ts file")
+      const sender = seam.__lecodesPushSend
+      if (!sender) throw new Error("pushChannel.send: no host sender installed")
+      const ids = pushTargetIds(user)
+      if (!message || typeof message !== "object") throw new Error("pushChannel.send: send(user, { title, … })")
+      const title = typeof message.title === "string" ? message.title.trim() : ""
+      if (!title) throw new Error("pushChannel.send: a notification needs a title")
+      if (title.length > TITLE_MAX) throw new Error(`pushChannel.send: the title is longer than ${TITLE_MAX} characters`)
+      if (ids.length === 0) return { sent: 0 }
+      return sender(ch.__id, ids, { ...message, title })
+    },
+    onTap() {
+      throw new Error("pushChannel.onTap: the app listens, the server sends")
+    },
+    onMessage() {
+      throw new Error("pushChannel.onMessage: the app listens, the server sends")
+    },
+  }
+  return ch as unknown as PushChannel<D>
+}
+
+export const isPushChannel = (v: unknown): v is PushChannelRecord =>
+  typeof v === "object" && v !== null && (v as PushChannelRecord).__pushChannel === true

package/src/server/runtime.ts

@@ -16,6 +16,7 @@ import type { AuthHost } from "./auth/host"
 import type { AuthState } from "./auth/types"
 import type { FilesHost, ResourceReader } from "./files/host"
 import { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
+import { isPushChannel, type PushChannelRecord } from "./pushChannel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
 import { takeRegisteredDbs } from "./db/defineDb"
@@ -26,6 +27,8 @@ export type ServerRegistration = { modules: Record<string, Record<string, unknow
 export type LoadedServer = {
   endpoints: Map<string, (...args: any[]) => unknown>
   channels: Map<string, ChannelRecord>
+  /** The push channels (`pushChannel()` exports): their presence is what makes a response ask a signed-in device to register. */
+  pushChannels: Map<string, PushChannelRecord>
   /** The project's `defineDb` handle — exported or not (the bundle registers it on globalThis); none or one. */
   dbs: Db<any>[]
   manifest: ServerManifest
@@ -38,7 +41,7 @@ export const loadServerModules = (
   reg: ServerRegistration | undefined = (globalThis as any).__lecodesServer,
 ): LoadedServer => {
   if (!reg) throw new Error("loadServerModules: no server bundle registered (globalThis.__lecodesServer)")
-  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), dbs: [], manifest: reg.manifest }
+  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), pushChannels: new Map(), dbs: [], manifest: reg.manifest }
   for (const [mod, exports] of Object.entries(reg.modules)) {
     // the compile's word on each export (serverSplit.ts): a function that is not async is the
     // server's helper, never an endpoint — an old manifest without kinds counts every function
@@ -47,6 +50,7 @@ export const loadServerModules = (
       const id = `${mod}#${name}`
       if (typeof value === "function") { if (kinds.get(name) !== "other") out.endpoints.set(id, value as (...args: any[]) => unknown) }
       else if (isChannel(value)) { value.__id = id; out.channels.set(id, value) }
+      else if (isPushChannel(value)) { value.__id = id; out.pushChannels.set(id, value) }
       else if (isDb(value)) out.dbs.push(value)
     }
   }
@@ -61,10 +65,12 @@ export const loadServerModules = (
   return out
 }
 
-/** The wire envelope. `session` = a token the client must store from now on (new guest session / rotation). */
+/** The wire envelope. `session` = a token the client must store from now on (new guest session / rotation).
+ *  `push` = the device is asked to register for notifications: its session is signed in, has no push address,
+ *  and the project has push channels (the transport registers, once per run — the OS prompt comes then). */
 export type InvokeResult =
-  | { ok: true, result: unknown, session?: string }
-  | { ok: false, status: number, message: string, session?: string }
+  | { ok: true, result: unknown, session?: string, push?: true }
+  | { ok: false, status: number, message: string, session?: string, push?: true }
 
 export type InvokerOptions = {
   /** Validate args against the manifest's param schemas (default true; endpoints without a schema pass). */
@@ -104,10 +110,13 @@ const dbStatus = (e: unknown): number | null => {
 const als = new AsyncLocalStorage<RequestContext>()
 const installProvider = () => setRequestProvider(() => als.getStore())
 
-// A token minted/rotated during the call rides on the envelope (the client transport stores it).
-const withSession = (r: InvokeResult, rc: RequestContext): InvokeResult => {
-  const issued = (rc.auth as AuthState | undefined)?.issuedToken
-  return issued ? { ...r, session: issued } : r
+// A token minted/rotated during the call rides on the envelope (the client transport stores it); so does the
+// request to register the device for notifications, when a signed-in session has no address and there are
+// push channels to hear.
+const envelope = (server: LoadedServer) => (r: InvokeResult, rc: RequestContext): InvokeResult => {
+  const s = rc.auth as AuthState | undefined
+  const out = s?.issuedToken ? { ...r, session: s.issuedToken } : r
+  return s && s.userId !== null && !s.pushAddress && server.pushChannels.size ? { ...out, push: true } : out
 }
 
 export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) => {
@@ -117,6 +126,7 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
   const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
   const auth = opts.auth ?? null
   const files = opts.files ?? null
+  const withSession = envelope(server)
 
   return async (id: string, args: unknown[], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
     const fn = server.endpoints.get(id)
@@ -233,6 +243,7 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
   const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
   const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
   const auth = opts.auth ?? null
+  const withSession = envelope(server)
   return async (channelId: string, args: unknown[] = [], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
     const ch = server.channels.get(channelId)
     if (!ch) return { ok: false, status: 404, message: `Unknown channel ${channelId}` }
@@ -258,3 +269,4 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
 }
 
 export { setChannelPublisher, setRequestProvider }
+export { setPushSender } from "./pushChannel"

package/src/ui/UIInput.ts

@@ -168,8 +168,8 @@ class InputElement<T extends "input" | "textarea"> extends Element<T> {
 export function UIInput(): UIInput;
 export function UIInput(style: UIInputStyle): UIInput;
 export function UIInput(style?: UIInputStyle): UIInput {
-  // One text line as the floor — an unstyled input must never collapse to 0 height.
-  return new InputElement("input", { minHeight: "1.2em", ...style })
+  // A touch target as the floor — an unstyled input is a finger high, never a text line.
+  return new InputElement("input", { minHeight: 44, ...style })
 }
 
 /**

package/src/ui/UINode.ts

@@ -176,7 +176,7 @@ export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyl
   flex?: number | string,
   flexGrow?: number,
   flexShrink?: number,
-  flexBase?: UIValue | `${number}%` | "auto",
+  flexBasis?: UIValue | `${number}%` | "auto",
   alignSelf?: "flex-start" | "center" | "flex-end" | "stretch",
   display?: "none" | "flex"
 }

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.2.13"
+export const SDK_VERSION = "2.2.14"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {