lecodes-sdk 2.2.13 → 2.2.14

package/dist/global.d.ts

@@ -173,6 +173,8 @@ declare global {
   const __channel: typeof SDK.__channel
   const __compOp: typeof SDK.__compOp
   const __compWrite: typeof SDK.__compWrite
+  const __pushChannel: typeof SDK.__pushChannel
+  const __pushEnable: typeof SDK.__pushEnable
   const __rpc: typeof SDK.__rpc
   const __serverOnly: typeof SDK.__serverOnly
   const __uiMap: typeof SDK.__uiMap
@@ -478,10 +480,14 @@ declare global {
   type Point = SDK.Point
   type PresentOptions = SDK.PresentOptions
   type Presentable = SDK.Presentable
+  type PushChannel<D extends Record<string, unknown> | undefined = undefined> = SDK.PushChannel<D>
   type PushEvent = SDK.PushEvent
+  type PushMessage<D> = SDK.PushMessage<D>
+  type PushNotification<D> = SDK.PushNotification<D>
   type PushPayload = SDK.PushPayload
   type PushRegisterOptions = SDK.PushRegisterOptions
   type PushStatus = SDK.PushStatus
+  type PushTarget = SDK.PushTarget
   type QRScanner = SDK.QRScanner
   type Quat = SDK.Quat
   type RTCConfiguration = SDK.RTCConfiguration
@@ -674,10 +680,15 @@ declare global {
   const channel: typeof SERVER.channel
   const defineDb: typeof SERVER.defineDb
   const model: typeof SERVER.model
+  const pushChannel: typeof SERVER.pushChannel
   const ref: typeof SERVER.ref
   const request: typeof SERVER.request
   const t: typeof SERVER.t
   type ApiError = SERVER.ApiError
+  type PushChannel<D extends Record<string, unknown> | undefined = undefined> = SERVER.PushChannel<D>
+  type PushMessage<D> = SERVER.PushMessage<D>
+  type PushNotification<D> = SERVER.PushNotification<D>
+  type PushTarget = SERVER.PushTarget
   type StoredFile = SERVER.StoredFile
   type StoredImage = SERVER.StoredImage
 }

package/dist/types/inject.d.ts

@@ -22,9 +22,10 @@ export { device, type HapticStyle, type MotionOptions } from "./runtime/device";
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input";
 export { WebSocket } from "./runtime/net";
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net";
-export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc";
+export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc";
 export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource";
 export type { ChannelSubscription } from "./server/channel";
+export type { PushChannel, PushMessage, PushNotification, PushTarget } from "./server/pushChannel";
 export type { StoredFile, StoredImage } from "./server/files/models";
 export { AudioPlayer, VideoPlayer } from "./runtime/media";
 export { Sound, type SoundOptions } from "./audio/Sound";
@@ -76,7 +77,7 @@ export { ARScene, Anchor, ImageAnchor, ARPlane, type ARSceneOptions, type AROpen
 export { AudioRecorder, type AudioRecorderEvents, type RecorderState, type RecordOptions, type Recording, type EndReason } from "./plugins/gen/audio-recorder/sdk/audio-recorder";
 export { SpeechRecognizer, type SpeechRecognizerEvents, type SpeechOptions, type SpeechResult, type SpeechErrorCode } from "./plugins/gen/speech/sdk/speech";
 export { MapView, type MapOptions, type MapStyle, type MapStyleName, type MapCamera, type MapTap, type LngLat, type CameraMove, type FitOptions, type MapPaddingValues, type MarkerItem, type MarkerTap, type MarkerLayer, type MarkerLayerOptions, type LineLayer, type LineLayerOptions, type UserLocationOptions, } from "./plugins/gen/map/sdk/map";
-export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push";
+export { Push, __pushEnable, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push";
 export { Browser, WebView, type BrowserOpenOptions, type WebViewParams, type WebViewEvents } from "./plugins/gen/browser/sdk/browser";
 export { RTCPeerConnection, MediaStream, MediaStreamTrack, RTCDataChannel, RTCRtpSender, RTCRtpReceiver, RTCRtpTransceiver, RTCSessionDescription, RTCIceCandidate, RTCEventTarget, mediaDevices, RTCVideoView, type RTCConfiguration, type RTCVideoViewOptions, type MediaStreamConstraints, type RTCIceCandidateInit, type RTCPeerConnectionIceEvent, type RTCTrackEvent, type RTCDataChannelEvent, type RTCMessageEvent, type RTCErrorEvent, type RTCEvent, type RTCEventListener, } from "./plugins/gen/webrtc/sdk/webrtc";
 export { Service } from "./plugins/service";

package/dist/types/plugin.d.ts

@@ -23,6 +23,9 @@ export { Quat, type QuatLike } from "./math/quat";
 export { Mat4 } from "./math/mat4";
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch";
 export type { DismissOptions } from "./ui/presentable";
+/** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
+ *  reads the device's address from, registers through, and a push channel's handlers are kept by. */
+export { _pushRuntime, type PushRuntime } from "./runtime/pushSeam";
 /** Signed 32-bit integer on the wire. */
 export type i32 = number;
 /** Double on the wire — also every integer that can leave 32 bits (a millisecond time stamp). */

package/dist/types/plugins/gen/push/sdk/push.d.ts

@@ -4,6 +4,11 @@ export type PushEvent = keyof PushEvents;
 /**
  * Remote push notifications. `Push.isSupported` reports whether this host registered the
  * service — check it before offering notification features.
+ *
+ * A project with a backend needs none of this: its `pushChannel()` exports are heard with their
+ * own `onTap` / `onMessage`, and the device is registered when the server asks (after a sign-in).
+ * `Push` is for the rest — a permission asked at a moment of the app's choosing, and the
+ * notifications sent outside a channel (a push key, `lecodes pn send`).
  */
 export declare const Push: {
     /** Whether this host registered a "push" service. */
@@ -15,9 +20,11 @@ export declare const Push: {
     register(options?: PushRegisterOptions): Promise<PushRegistration>;
     /** Remove this device's registration (the address stops receiving). */
     unregister(): Promise<void>;
-    /** The notification that cold-started this app run, or null. Stable across calls. */
-    getLaunch(): Promise<PushPayload | null>;
-    /** "message" = received while the app is open; "tap" = the user tapped one while it ran. */
+    /** The notifications sent outside a push channel: "tap" = tapped (the one that started the app
+     *  too); "message" = arrived while the app is open (the app shows it, the host no banner). */
     addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void;
     removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void;
 };
+/** Installs the push runtime for the SDK's transport and its push-channel proxies (lecodes-sdk/plugin
+ *  `_pushRuntime`). A line of every server stub of a project with push channels — never app code. */
+export declare const __pushEnable: () => void;

package/dist/types/plugins/gen/push/sdk/push.gen.d.ts

@@ -1,9 +1,9 @@
 import { ServiceChannel } from "../../../../plugin";
-import type { PushEvents, PushParams, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract";
+import type { PushEvents, PushHandled, PushParams, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract";
 /** What the halves register under. */
 export declare const NAME = "push";
 /** The contract's version: the highest `@since` of its members. */
-export declare const VERSION = 1;
+export declare const VERSION = 2;
 /** Permission + registration state. Never prompts. */
 export declare const getStatus: (service: ServiceChannel<PushEvents>) => Promise<PushStatus>;
 /** Ask for the permission (the first time) and register this device. Idempotent.
@@ -14,8 +14,12 @@ export declare const register: (service: ServiceChannel<PushEvents>, options?: P
 export declare const unregister: (service: ServiceChannel<PushEvents>) => Promise<void>;
 /** The notification that cold-started this world, or null. Stable across calls. */
 export declare const getLaunch: (service: ServiceChannel<PushEvents>) => Promise<PushPayload | null>;
+/** Which notifications the app handles itself in the foreground; the rest get the system banner.
+ *  Until it is called nothing is handled.
+ *  Contract version 2: an older half rejects the call — ask `supports("setMessageHandled")`. */
+export declare const setMessageHandled: (service: ServiceChannel<PushEvents>, handled: PushHandled) => Promise<void>;
 /** A method of the contract. */
-export type Method = "getStatus" | "register" | "unregister" | "getLaunch";
+export type Method = "getStatus" | "register" | "unregister" | "getLaunch" | "setMessageHandled";
 /** Whether this host has the service "push" — and, given a method, a half new enough for it
  *  (a method added after the first version of the contract is tagged `@since`). */
 export declare const supports: (method?: Method) => boolean;
@@ -32,4 +36,8 @@ export declare class PushBase extends ServiceChannel<PushEvents> {
     unregister(): Promise<void>;
     /** The notification that cold-started this world, or null. Stable across calls. */
     getLaunch(): Promise<PushPayload | null>;
+    /** Which notifications the app handles itself in the foreground; the rest get the system banner.
+     *  Until it is called nothing is handled.
+     *  Contract version 2: an older half rejects the call — ask `supports("setMessageHandled")`. */
+    setMessageHandled(handled: PushHandled): Promise<void>;
 }

package/dist/types/runtime/pushSeam.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The seam between the app's transport (./rpc.ts) and the push plugin's wrapper (src/plugins/gen/push/sdk/push.ts).
+ *
+ * A push channel (`pushChannel()` of a *.server.ts file — src/server/pushChannel.ts) is heard in the app through
+ * the plugin: its taps and foreground arrivals come off the plugin's service. The transport, for its part, tells
+ * the server the device's address (the `x-lecodes-push` header of every call) and registers the device when the
+ * server asks for it (the envelope's `push: true`). Neither may import the wrapper: an app without push channels
+ * would then carry the plugin. So the wrapper installs itself here — `__pushEnable()`, a line the compiler puts at
+ * the top of every server stub of a project with push channels — and the transport reads what is installed.
+ */
+export type PushRuntime = {
+    /** This device's address for the app, once known (after a registration, or the status of an earlier one). */
+    address(): string | null;
+    /** The server asked this device to register: once per run, prompt-free when the permission was given,
+     *  nothing past a refusal. */
+    requestRegister(): void;
+    /** Hear the taps ("tap") or the foreground arrivals ("message") of one push channel, by its id. Returns the remover. */
+    on(kind: "tap" | "message", channel: string, handler: (payload: any) => void): () => void;
+};
+/** What the wrapper installed; null = the app has no push channels (or the plugin is not in the bundle). */
+export declare const _pushRuntime: {
+    current: PushRuntime | null;
+};

package/dist/types/runtime/rpc.d.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"?:"…"}
@@ -38,3 +39,16 @@ export declare const __channel: (serverUrl: string, id: string) => {
     subscribe(...all: unknown[]): ChannelSubscription;
     publish(): never;
 };
+/**
+ * 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 declare const __pushChannel: (serverUrl: string, id: string) => {
+    onTap: (handler: unknown) => ChannelSubscription;
+    onMessage: (handler: unknown) => ChannelSubscription;
+    send(): never;
+};

package/dist/types/server/auth/models.d.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.
  *
@@ -85,6 +86,17 @@ export declare const sessionFields: (userModel: string) => {
         isId: false;
         model: "";
     }>;
+    /** 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: import("../db").Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
     user: import("../db").Field<never, {
         kind: "one";
         scalar: "";

package/dist/types/server/auth/types.d.ts

@@ -11,6 +11,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/dist/types/server/inject.d.ts

@@ -1,6 +1,7 @@
 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/dist/types/server/pushChannel.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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;
+}>;
+/** Host hook (runner / local backend / test harness): where `send` delivers to. */
+export declare const setPushSender: (sender: PushSender | null) => void;
+/** The ids of `send`'s first argument, each once; throws on what is not a user. */
+export declare const pushTargetIds: (user: unknown) => number[];
+export declare const pushChannel: <D extends Record<string, unknown> | undefined = undefined>() => PushChannel<D>;
+export declare const isPushChannel: (v: unknown) => v is PushChannelRecord;

package/dist/types/ui/UINode.d.ts

@@ -138,7 +138,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/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.2.13";
+export declare const SDK_VERSION = "2.2.14";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from