lecodes-sdk 2.4.1 → 2.4.2

package/dist/types/plugins/gen/browser/contract.d.ts

@@ -0,0 +1,108 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/browser/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// browser — web content inside the app, on the two surfaces the platforms give:
+//   - the SYSTEM SHEET (the "browser" service): SFSafariViewController / ASWebAuthenticationSession on
+//     iOS, Chrome Custom Tabs on Android, a popup on the web. It shares the system browser's logins,
+//     passkeys and Apple Pay, and OAuth providers accept it. The app sees nothing of the page.
+//   - the EMBEDDED PAGE (the "webView" view): WKWebView / android.webkit.WebView / an iframe. A tree
+//     node the app embeds or presents fullscreen, with navigation events the app acts on.
+//
+// The hosts are dumb on purpose: they intercept a URL prefix and report it, forward the platform's
+// callback URL, hand a non-http link to the system. Which URL ends a flow and what it means is the
+// app's side (`Browser.open` in sdk/).
+
+import type { Json, Service, View } from "../../../plugin"
+
+// ---- the sheet ------------------------------------------------------------------------------------
+
+export interface BrowserParams {}
+
+export interface BrowserOpenOptions {
+  /** An auth flow: the scheme the provider redirects back to (`myshop` of `myshop://oauth`). iOS
+   *  runs an ASWebAuthenticationSession and resolves `open` with the callback URL itself. Android
+   *  and the web have nothing to do here: the redirect reaches the app as its "url" event. */
+  callbackScheme?: string
+  /** A private session: no cookies shared with the system browser. Honored on iOS (with a
+   *  callbackScheme), ignored elsewhere. Default false. */
+  ephemeral?: boolean
+  /** The sheet's tint, "#RRGGBB". */
+  color?: string
+}
+
+export interface BrowserResult {
+  /** The callback URL the platform intercepted (iOS, with a callbackScheme); absent when the sheet
+   *  was dismissed. */
+  url?: string
+}
+
+export interface BrowserEvents {
+  /** The sheet went away: the user dismissed it, the platform handed back the callback, or
+   *  close(). */
+  closed: void
+}
+
+export interface Browser extends Service<"browser", BrowserParams, BrowserEvents> {
+  /** Show `url` in the system's in-app browser sheet. Resolves when the sheet is dismissed — with
+   *  the callback URL when the platform intercepted one. One sheet at a time.
+   *  @rejects busy invalid */
+  show(url: string, options?: BrowserOpenOptions): Promise<BrowserResult>
+  /** Dismiss the sheet; a no-op without one. */
+  dismiss(): Promise<void>
+}
+
+// ---- the embedded page ----------------------------------------------------------------------------
+
+export interface WebViewParams {
+  /** What to load first. */
+  url?: string
+  /** Main-frame URLs that END a flow: a navigation whose URL starts with one is NOT loaded, the
+   *  view emits `stop` instead. */
+  stops?: string[]
+  /** Install `window.lecodes.postMessage(data)` for the page (the `message` event) and let
+   *  `postMessage` reach it (`window.lecodes.onMessage`). Default false — a user script disables
+   *  Apple Pay in that WKWebView, so a checkout page wants it off. */
+  bridge?: boolean
+  /** A navigation to a non-http(s) URL — tel:, mailto:, intent:, a bank's app in a checkout:
+   *  "open" hands it to the system, "block" drops it. Default "open". */
+  externalLinks?: "open" | "block"
+  userAgent?: string
+  /** A private session: no cookies or storage kept after the view goes. Default false. */
+  ephemeral?: boolean
+}
+
+export interface WebViewEvents {
+  /** A main-frame navigation started. */
+  navigate: { url: string }
+  /** The page finished loading. */
+  load: { url: string, title: string }
+  /** The page failed to load. */
+  error: { url: string, message: string }
+  /** A stop URL was reached: the navigation was cancelled, the page did not load. */
+  stop: { url: string }
+  /** The page called `window.lecodes.postMessage(data)` (with `bridge`). */
+  message: { data: Json }
+  /** The page called `window.close()`. */
+  exit: void
+}
+
+export interface WebView extends View<"webView", WebViewParams, WebViewEvents> {
+  /** Load `url`, with extra request headers for the first request. @rejects invalid */
+  load(url: string, headers?: { [name: string]: string }): Promise<void>
+  /** Show `html` as the page; relative URLs in it resolve against `baseUrl`. */
+  loadHtml(html: string, baseUrl?: string): Promise<void>
+  /** Replace the stop list (see WebViewParams.stops). */
+  setStops(stops: string[]): Promise<void>
+  reload(): Promise<void>
+  /** Stop the current load. */
+  stopLoading(): Promise<void>
+  goBack(): Promise<void>
+  goForward(): Promise<void>
+  canGoBack(): Promise<boolean>
+  /** Run `js` in the page and return what it evaluates to, as JSON. On iOS this disables Apple Pay
+   *  in the view until its next navigation. @rejects failed */
+  evaluate(js: string): Promise<Json>
+  /** Deliver `data` to the page's `window.lecodes.onMessage(data)` (with `bridge`). */
+  postMessage(data: Json): Promise<void>
+  /** Clear the cookies and the storage of this view's session. */
+  clearData(): Promise<void>
+}

package/dist/types/plugins/gen/camera/contract.d.ts

@@ -0,0 +1,27 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/camera/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// camera — a live camera preview with still capture.
+// The contract of the WIRE: what the app-facing `CameraView` (sdk/) and the halves (ios/, android/,
+// web/) agree on. The generator reads this file; nothing else describes the channel.
+
+import type { File, View } from "../../../plugin"
+
+export type Facing = "front" | "back"
+
+export interface CameraParams {
+  /** Default "back". */
+  facingMode?: Facing
+}
+
+export interface CameraEvents {
+  /** The preview could not start or stopped (no camera, the stream was refused). */
+  error: { message: string }
+}
+
+export interface CameraView extends View<"camera", CameraParams, CameraEvents> {
+  /** Capture a still frame as a JPEG.
+   *  @rejects failed */
+  takePhoto(): Promise<File>
+  /** Switch the camera while the preview is live. */
+  setFacingMode(mode: Facing): Promise<void>
+}

package/dist/types/plugins/gen/geolocation/contract.d.ts

@@ -0,0 +1,52 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/geolocation/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// geolocation — the device position.
+// The wire has ONE watch per session (startWatch / stopWatch + the `position` event); the
+// app-facing `Geolocation.watch(callback)` fans it out to its subscribers in sdk/.
+//
+// A session opens without a prompt. The OS permission is the calls' (`@permission location`): the
+// host asks before the first call that needs the position, the halves never do.
+
+import type { Service, f64 } from "../../../plugin"
+
+export interface GeoOptions {
+  /** Prefer the precise (GPS) provider — slower first fix, more battery. Default false. */
+  highAccuracy?: boolean
+  /** getCurrent only: reject with "timeout" when no fix arrives in this many ms. */
+  timeout?: f64
+}
+
+export interface GeoPosition {
+  latitude: f64
+  longitude: f64
+  /** Horizontal accuracy radius, meters. */
+  accuracy: f64
+  /** Meters above sea level; null when the provider does not know. */
+  altitude: f64 | null
+  /** Direction of travel, degrees clockwise from north; null when stationary or unknown. */
+  heading: f64 | null
+  /** Ground speed, m/s; null when unknown. */
+  speed: f64 | null
+  /** When the fix was taken, ms since the epoch. */
+  timestamp: f64
+}
+
+export interface GeolocationParams {}
+
+export interface GeolocationEvents {
+  /** A fix of the live watch. */
+  position: GeoPosition
+}
+
+export interface Geolocation extends Service<"geolocation", GeolocationParams, GeolocationEvents> {
+  /** One fix.
+   *  @permission location
+   *  @rejects unavailable timeout */
+  getCurrent(options?: GeoOptions): Promise<GeoPosition>
+  /** Start the session's watch; resolves once it is live (the provider started).
+   *  A second call while watching resolves at once and keeps the first call's options.
+   *  @permission location
+   *  @rejects unavailable */
+  startWatch(options?: GeoOptions): Promise<void>
+  stopWatch(): Promise<void>
+}

package/dist/types/plugins/gen/map/contract.d.ts

@@ -0,0 +1,144 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/map/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// map — a vector map (maplibre-native on iOS / Android, maplibre-gl in the browser).
+// The wire is lower than the app-facing `MapView`: the wrapper in sdk/ resolves a style to a url or
+// to text, turns marker items into GeoJSON, queues calls until `ready` and re-applies the
+// style-lifetime state (layers, data, padding, the user puck) after every style load.
+//
+// The plugin never touches the location hardware: the user puck is fed by the app.
+
+import type { Json, View, f64 } from "../../../plugin"
+
+/** `[longitude, latitude]` — GeoJSON order. */
+export type LngLat = [f64, f64]
+
+export interface MapParams {
+  /** A style URL the map fetches itself. */
+  style?: string
+  /** A style as JSON text; wins over `style`. It has no base url: every url INSIDE it (sources,
+   *  sprite, glyphs) must be absolute. */
+  styleJson?: string
+  center?: LngLat
+  /** Default 12 with a center. */
+  zoom?: f64
+  minZoom?: f64
+  maxZoom?: f64
+  /** Degrees clockwise from north. */
+  bearing?: f64
+  /** Degrees from the vertical. */
+  pitch?: f64
+  /** The two-finger rotate gesture. Default true. */
+  rotate?: boolean
+  /** The two-finger tilt gesture. Default false. */
+  tilt?: boolean
+}
+
+export interface MapCamera {
+  center: LngLat
+  zoom: f64
+  bearing: f64
+  pitch: f64
+}
+
+/** A feature of a managed source under a tap. */
+export interface MapFeature {
+  /** The source's name — the layer's name in the app. */
+  source: string
+  id: string | f64 | null
+  properties: { [key: string]: Json }
+}
+
+export interface MapTap {
+  lngLat: LngLat
+  /** View-space point, logical px. */
+  point: [f64, f64]
+  /** Absent for a tap that hit no feature of a managed source. A tap on a CLUSTER zooms in and
+   *  sends no event. */
+  feature?: MapFeature
+}
+
+export interface MapEvents {
+  /** The style loaded and the map takes calls. Fires again after every style reload. */
+  ready: void
+  tap: MapTap
+  /** The camera settled after a gesture or an animation. */
+  moveEnd: MapCamera
+  /** A problem that is never fatal: a style that would not load, a source out of reach. */
+  error: { message: string }
+}
+
+export type MapLayerKind = "markers" | "line"
+
+/** The keys of both kinds; a half reads the ones of the kind it is asked for. */
+export interface MapLayerOptions {
+  /** markers: group nearby markers (a cluster tap zooms in). Default false. */
+  cluster?: boolean
+  /** markers: px. Default 50. */
+  clusterRadius?: f64
+  /** markers: the zoom at which clusters stop forming. */
+  clusterMaxZoom?: f64
+  /** line. */
+  color?: string
+  /** line: px. Default 4. */
+  width?: f64
+  /** line: 0–1. Default 1. */
+  opacity?: f64
+}
+
+export interface MapCameraMove {
+  zoom?: f64
+  bearing?: f64
+  pitch?: f64
+  /** flyTo only: ms. Default 600. */
+  duration?: f64
+}
+
+/** Px, or a share of the view's size as "NN%". */
+export type MapInset = f64 | string
+
+export interface MapPadding {
+  top?: MapInset
+  left?: MapInset
+  bottom?: MapInset
+  right?: MapInset
+}
+
+export interface MapFitOptions {
+  /** Around the points: px on every edge, or per edge. Added to the view padding. */
+  padding?: f64 | MapPadding
+  /** Default: 16 for one point, none otherwise. */
+  maxZoom?: f64
+  /** Default true. */
+  animate?: boolean
+}
+
+export interface MapUserLocationOptions {
+  /** Meters — the halo around the dot. */
+  accuracy?: f64 | null
+  /** Degrees clockwise from north — the direction wedge; null hides it. */
+  heading?: f64 | null
+}
+
+export interface MapView extends View<"map", MapParams, MapEvents> {
+  /** Make sure the GeoJSON source `source` exists. A source the style declares is used as is (its
+   *  layers draw, only data flows); otherwise the half creates it with the default layers of `kind`.
+   *  @rejects notReady */
+  ensureLayer(source: string, kind: MapLayerKind, options?: MapLayerOptions): Promise<void>
+  removeLayer(source: string): Promise<void>
+  /** Replace the data of a GeoJSON source: a Feature or a FeatureCollection.
+   *  @rejects notReady */
+  setData(source: string, geojson: Json): Promise<void>
+
+  flyTo(center: LngLat, options?: MapCameraMove): Promise<void>
+  jumpTo(center: LngLat, options?: MapCameraMove): Promise<void>
+  /** Fit the camera to the points.
+   *  @rejects noPoints */
+  fitPoints(points: LngLat[], options?: MapFitOptions): Promise<void>
+  /** The part of the view covered by the app's UI; camera moves center inside the rest. */
+  setPadding(padding: MapPadding): Promise<void>
+  /** @rejects notReady */
+  getCamera(): Promise<MapCamera>
+
+  /** Move the user puck; null hides it. */
+  setUserLocation(lngLat: LngLat | null, options?: MapUserLocationOptions): Promise<void>
+}

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

@@ -0,0 +1,83 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/push/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// push — remote notifications (APNs on iOS, FCM on Android).
+// The host owns the OS token, the permission prompt and the registration with the le.codes relay;
+// the app sees the opaque project-scoped ADDRESS and the payloads, never the raw token.
+//
+// An OPEN SESSION is the delivery pipe of the events. Opening one is free (no prompt, no I/O).
+// Identity: every call is attributed to the world that makes it (the project's uuid, held by the
+// host); a world without one rejects "unavailable" BEFORE any permission path.
+//
+// A notification reaches the JS world through this channel ALONE: a tap is the "tap" event (or
+// `getLaunch()` for the one that started the process — the SDK's wrapper replays it into the first
+// "tap" listener), a foreground arrival is "message". Its `url` is the app's to route — it does NOT
+// ride the app's deep-link path (`app.launchUrl`, the "url" event).
+
+import type { Json, Service, i32 } from "../../../plugin"
+
+/** A delivered notification, as the app sees it. */
+export interface PushPayload {
+  /** The push channel it was sent through — the id of the `pushChannel()` export of the project's
+   *  server (`<path>#<name>`). Absent = sent outside one (a push key, `lecodes pn send`). */
+  channel?: string
+  title: string
+  body?: string
+  /** A deep link, for the app to open itself (it does not ride `app.launchUrl`). */
+  url?: string
+  /** The developer's own JSON object, ≤ 2 KB serialized. */
+  data?: { [key: string]: Json }
+  badge?: i32
+}
+
+export interface PushStatus {
+  /** The OS permission of the host app. "prompt" = not asked yet. */
+  permission: "granted" | "denied" | "prompt"
+  /** Whether this device holds a registration (an address) for this app. */
+  registered: boolean
+  /** The device's address for this app, when it is registered. @since 2 */
+  address?: string
+}
+
+export interface PushRegisterOptions {
+  /** The app's OWN user id. Client-asserted and unverified. The registration reflects the latest
+   *  call: registering without it clears it. */
+  user?: string
+}
+
+export interface PushRegistration {
+  address: string
+}
+
+/** What the app shows itself when a notification arrives while it is in the foreground (the
+ *  "message" event): the host shows the system banner for every other one. */
+export interface PushHandled {
+  /** The push channels with a foreground handler. */
+  channels: string[]
+  /** Whether notifications sent outside a channel have one. */
+  untyped: boolean
+}
+
+export interface PushParams {}
+
+export interface PushEvents {
+  /** Arrived while this app was in the foreground and the app handles it (PushHandled): no banner. */
+  message: PushPayload
+  /** Tapped while the world was alive. */
+  tap: PushPayload
+}
+
+export interface Push extends Service<"push", PushParams, PushEvents> {
+  /** Permission + registration state. Never prompts. */
+  getStatus(): Promise<PushStatus>
+  /** Ask for the permission (the first time) and register this device. Idempotent.
+   *  @rejects denied unavailable */
+  register(options?: PushRegisterOptions): Promise<PushRegistration>
+  /** Remove this device's registration.
+   *  @rejects unavailable */
+  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. @since 2 */
+  setMessageHandled(handled: PushHandled): Promise<void>
+}

package/dist/types/plugins/gen/qr-scanner/contract.d.ts

@@ -0,0 +1,16 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/qr-scanner/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// qr-scanner — a camera view that decodes QR codes.
+// A view with events only: the app opens / embeds it and listens.
+
+import type { View } from "../../../plugin"
+
+export interface QRScannerParams {}
+
+export interface QRScannerEvents {
+  /** One per decoded camera frame: the payload, or null for a frame with no readable code (it
+   *  repeats while the user aims). The same code may be reported more than once. */
+  scan: { data: string | null }
+}
+
+export interface QRScanner extends View<"qrScanner", QRScannerParams, QRScannerEvents> {}

package/dist/types/plugins/gen/speech/contract.d.ts

@@ -0,0 +1,67 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/speech/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// speech — speech recognition: the microphone to text, live (dictation, voice commands).
+// A session is ONE listening (the app-facing `SpeechRecognizer` opens one per `start()`): results
+// arrive as events, partial ones while the user speaks and a final one after, then `end`. The
+// permissions are the contract's (`@permission speech microphone` on start): the host asks, the
+// halves never do.
+//
+// The recognizer is the platform's: Apple's (SFSpeechRecognizer: on-device where the language
+// allows, else Apple's servers), Google's on Android (the device's RecognitionService — absent on a
+// phone without Google's app: `start` rejects "unavailable"), the browser's on the web (Chrome sends
+// the audio to Google; Safari to Apple). Languages and quality differ with them.
+
+import type { Service, f64 } from "../../../plugin"
+
+export interface SpeechOptions {
+  /** BCP-47 — "en-US", "ru-RU". Default: the device's language. */
+  language?: string
+  /** Keep listening and delivering results until `stop()`; default false: one utterance — the
+   *  listening ends after a pause in the speech. */
+  continuous?: boolean
+  /** Deliver partial results while the user speaks (`isFinal` false). Default true. */
+  interimResults?: boolean
+  /** Recognize on the device only — no audio leaves it; fewer languages, and "unavailable" where
+   *  the device cannot. Default false. The web ignores it. */
+  onDevice?: boolean
+}
+
+export interface SpeechResult {
+  /** The text so far (a partial), or of the utterance (final). */
+  transcript: string
+  isFinal: boolean
+  /** 0..1 when the recognizer says; null when it does not (partials, Android). */
+  confidence: f64 | null
+}
+
+export type SpeechErrorCode = "noSpeech" | "audio" | "network" | "denied" | "aborted" | "unavailable" | "failed"
+
+export interface SpeechParams {}
+
+export interface SpeechEvents {
+  /** A result: partials while speaking (when `interimResults`), then the final one. */
+  result: SpeechResult
+  /** The user started speaking. */
+  speechStart: void
+  /** The user stopped speaking (a pause): the final result follows. */
+  speechEnd: void
+  /** The listening is over — after the final result, after `stop()` / `abort()`, after an error. */
+  end: void
+  /** The listening failed; `end` follows. "noSpeech": nothing was heard (not continuous). */
+  error: { code: SpeechErrorCode, message: string }
+}
+
+export interface Speech extends Service<"speech", SpeechParams, SpeechEvents> {
+  /** Start listening. One listening per session: a second start rejects "busy". "unavailable":
+   *  no recognizer on this device, or none for the language / on the device.
+   *  @permission speech microphone
+   *  @rejects busy unavailable failed */
+  start(options?: SpeechOptions): Promise<void>
+  /** Stop listening and finish: the final result of what was heard, then `end`. Not listening is
+   *  not an error. */
+  stop(): Promise<void>
+  /** Stop and drop what was heard: `end`, no result. */
+  abort(): Promise<void>
+  /** The languages this host recognizes, BCP-47; empty when the host cannot say (the web). */
+  supportedLanguages(): Promise<string[]>
+}