lecodes-sdk 2.2.13 → 2.3.0

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.3.0"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {