@glassly/cloud-client 0.1.0-dev.0

package/src/modules/runtime/emitter.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview The single typed event emitter behind `cloud.runtime`'s `on*`.
+ *
+ * There is exactly one emitter so there is one source of truth for runtime
+ * events: the friendly per-event methods (`onTranscript`, `onConnected`, ...),
+ * the generic `on(event, cb)`, and `onAny(cb)` are all thin wrappers over this.
+ * Keying by an event map (`RuntimeEvents`) means event names are checked by the
+ * compiler and payloads are typed, so there are no magic strings to mistype.
+ *
+ * See docs/issues/004-cloud-client/design.md ("src/modules/runtime/emitter.ts").
+ */
+import type {
+  QuotaStatusPayload,
+  TranscriptionData,
+  TranslationData,
+  ProtocolError,
+} from "@glassly/cloud-protocol";
+import type { RuntimeSnapshot } from "./status";
+
+/**
+ * The runtime event map: event name to payload type.
+ *
+ * `transcript` / `translation` carry the canonical wire result types, so a
+ * consumer gets exactly what the cloud sent. `connected` has no payload (the
+ * fact of connecting is the whole signal), so its type is `void`. `error`
+ * carries the wire `ProtocolError` (a non-fatal one; fatal ones close the
+ * socket and surface as a reconnect), not a thrown JS error.
+ */
+export interface RuntimeEvents {
+  transcript: TranscriptionData;
+  translation: TranslationData;
+  /** Plan-quota block state changed for a metered stream (stream.quota). */
+  quota: QuotaStatusPayload;
+  connected: void;
+  disconnected: { reason: string };
+  status: RuntimeSnapshot;
+  error: ProtocolError;
+}
+
+/** A handler stored for a single event name, payload typed by the map. */
+type Listener<K extends keyof RuntimeEvents> = (data: RuntimeEvents[K]) => void;
+
+/** A handler that receives every event, used for forwarding and logging. */
+type AnyListener = (event: keyof RuntimeEvents, data: unknown) => void;
+
+/**
+ * A typed multi-listener emitter for runtime events.
+ *
+ * Listeners are kept in a `Set` per event so the same handler is not registered
+ * twice and `off` is an O(1) removal. `onAny` listeners are kept separately and
+ * fired on every `emit`, which is what powers island re-emitting all runtime
+ * events without naming each one.
+ */
+export class RuntimeEmitter {
+  // One listener set per event name. A `Map` keyed by the event name keeps
+  // dispatch touching only the handlers for the event that fired. The stored set
+  // is typed loosely (the element type varies per key, which a single field
+  // cannot express); the public `on`/`off`/`emit` signatures below are fully
+  // typed via the event map, so callers never see the loose inner type.
+  private readonly listeners = new Map<
+    keyof RuntimeEvents,
+    Set<Listener<keyof RuntimeEvents>>
+  >();
+
+  // Listeners that want every event, kept apart so `emit` can fan out to them
+  // after the per-event handlers run.
+  private readonly anyListeners = new Set<AnyListener>();
+
+  /**
+   * Subscribe to one event. Returns an unsubscribe function, which is the only
+   * way callers are expected to detach: holding the returned function means a
+   * caller never needs a reference to the original handler to remove it.
+   */
+  on<K extends keyof RuntimeEvents>(e: K, cb: Listener<K>): () => void {
+    let set = this.listeners.get(e);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(e, set);
+    }
+    set.add(cb as Listener<keyof RuntimeEvents>);
+    return () => this.off(e, cb);
+  }
+
+  /**
+   * Remove a previously registered handler for one event. A no-op if the handler
+   * was never registered, so double-unsubscribe is safe.
+   */
+  off<K extends keyof RuntimeEvents>(e: K, cb: Listener<K>): void {
+    this.listeners.get(e)?.delete(cb as Listener<keyof RuntimeEvents>);
+  }
+
+  /**
+   * Subscribe to every event in one handler (for forwarding, iteration, or
+   * logging). The payload is `unknown` because it varies per event; a consumer
+   * narrows on the event name. Returns an unsubscribe function like `on`.
+   */
+  onAny(cb: AnyListener): () => void {
+    this.anyListeners.add(cb);
+    return () => {
+      this.anyListeners.delete(cb);
+    };
+  }
+
+  /**
+   * Deliver an event to its handlers, then to every `onAny` handler.
+   *
+   * We iterate over a copy of each listener set so a handler that subscribes or
+   * unsubscribes during dispatch does not mutate the set we are walking. A throw
+   * from one handler must not stop the others or skip the `onAny` fan-out, so
+   * each call is isolated and a failure is swallowed (the emitter has no logger;
+   * a handler owns its own error handling).
+   */
+  emit<K extends keyof RuntimeEvents>(e: K, d: RuntimeEvents[K]): void {
+    const set = this.listeners.get(e);
+    if (set) {
+      for (const cb of [...set]) {
+        try {
+          (cb as Listener<K>)(d);
+        } catch {
+          // A misbehaving listener must not break delivery to the others.
+        }
+      }
+    }
+    for (const cb of [...this.anyListeners]) {
+      try {
+        cb(e, d);
+      } catch {
+        // Same isolation for the catch-all listeners.
+      }
+    }
+  }
+}

package/src/modules/runtime/llm.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Runtime LLM API: provider-neutral completions.
+ *
+ * A thin client over the runtime's `/api/llm/*` REST endpoints. Plain
+ * request/response (no WebSocket push, like maps), so this module only needs
+ * the shared HTTP helper. The cloud holds the provider credential; the consumer
+ * (a miniapp via `session.ai`) never sees a key or a vendor response shape.
+ *
+ * The wire types are canonical in the protocol package (the runtime server uses
+ * the same ones); re-export them so a host gets them from this module.
+ */
+import type { HttpClient } from "../../http";
+import type {
+  LlmCompleteRequest,
+  LlmCompleteResult,
+  LlmGenerateJobCreated,
+  LlmGenerateJobStatus,
+  LlmGenerateRequest,
+  LlmGenerateResult,
+} from "@glassly/cloud-protocol";
+
+export type {
+  LlmCompleteRequest,
+  LlmCompleteResult,
+  LlmGenerateJobCreated,
+  LlmGenerateJobStatus,
+  LlmGenerateRequest,
+  LlmGenerateResult,
+  LlmGeneratedImage,
+  LlmMessage,
+  LlmProvider,
+  LlmStopReason,
+  LlmTool,
+  LlmToolCall,
+  LlmToolResult,
+  LlmUsage,
+} from "@glassly/cloud-protocol";
+
+const COMPLETE_PATH = "/api/llm/complete";
+const GENERATE_PATH = "/api/llm/generate";
+
+export interface LlmDeps {
+  http: HttpClient;
+}
+
+/** Extra per-call options that ride as headers rather than in the body. */
+export interface LlmCompleteOptions {
+  /**
+   * The user's own provider key. Sent as a header so it never lands in a
+   * request-body log. When present the platform bills that key instead of its
+   * own and the call is not metered.
+   */
+  userApiKey?: string;
+}
+
+export class Llm {
+  private readonly http: HttpClient;
+
+  constructor(deps: LlmDeps) {
+    this.http = deps.http;
+  }
+
+  /**
+   * Run one completion turn.
+   *
+   * NOT marked idempotent: a completion is a billed, non-deterministic
+   * generation, so a transparent retry after a transient blip could charge
+   * twice and return different text. Callers decide whether to retry.
+   */
+  complete(req: LlmCompleteRequest, opts: LlmCompleteOptions = {}): Promise<LlmCompleteResult> {
+    return this.http.post<LlmCompleteResult>(COMPLETE_PATH, req, {
+      headers: opts.userApiKey ? { "x-provider-key": opts.userApiKey } : undefined,
+    });
+  }
+
+  /**
+   * Run one agentic visual-generation call (server-side web search + code
+   * execution; returns text plus rendered images). Long-running — the server
+   * budgets ~150s of wall clock — and billed like a completion plus a flat
+   * surcharge, so like complete() it is NOT idempotent and never auto-retried.
+   */
+  generate(req: LlmGenerateRequest, opts: LlmCompleteOptions = {}): Promise<LlmGenerateResult> {
+    return this.http.post<LlmGenerateResult>(GENERATE_PATH, req, {
+      headers: opts.userApiKey ? { "x-provider-key": opts.userApiKey } : undefined,
+    });
+  }
+
+  /**
+   * Async flavor of generate(): start a pollable job. The job is per runtime
+   * instance and short-lived; a host that starts one polls generateJobStatus()
+   * every couple of seconds and cancels via cancelGenerateJob() when the
+   * consumer goes away. Old clouds without the surface answer 404 — callers
+   * fall back to the sync generate().
+   */
+  startGenerateJob(req: LlmGenerateRequest, opts: LlmCompleteOptions = {}): Promise<LlmGenerateJobCreated> {
+    return this.http.post<LlmGenerateJobCreated>(`${GENERATE_PATH}/jobs`, req, {
+      headers: opts.userApiKey ? { "x-provider-key": opts.userApiKey } : undefined,
+    });
+  }
+
+  /** Poll one job. GET, so the http layer already retries transient blips. */
+  generateJobStatus(jobId: string): Promise<LlmGenerateJobStatus> {
+    return this.http.get<LlmGenerateJobStatus>(`${GENERATE_PATH}/jobs/${encodeURIComponent(jobId)}`);
+  }
+
+  /** Cancel a running job so an abandoned run stops burning tokens. */
+  cancelGenerateJob(jobId: string): Promise<LlmGenerateJobStatus> {
+    return this.http.delete<LlmGenerateJobStatus>(`${GENERATE_PATH}/jobs/${encodeURIComponent(jobId)}`);
+  }
+}

package/src/modules/runtime/maps.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Runtime maps API: directions + reverse geocoding.
+ *
+ * A thin client over the runtime's `/api/maps/*` REST endpoints. Both calls are
+ * plain request/response (no WebSocket push, unlike camera), so this module only
+ * needs the shared HTTP helper. The cloud holds the maps provider token; the
+ * consumer (e.g. the navigation miniapp via the SDK) calls these and never sees
+ * a provider credential or a vendor-specific response shape.
+ *
+ * The wire types are canonical in the protocol package (the runtime server uses
+ * the same ones); re-export them so a host gets them from this module.
+ */
+import type { HttpClient } from "../../http";
+import type {
+  DirectionsRequest,
+  DirectionsResult,
+  LatLng,
+  MapsRenderTokenResult,
+  PlaceAutocompleteResult,
+  PlaceDetailsResult,
+  ReverseGeocodeResult,
+} from "@glassly/cloud-protocol";
+
+export type {
+  DirectionsRequest,
+  DirectionsResult,
+  Route,
+  RouteStep,
+  LatLng,
+  TravelMode,
+  ManeuverKind,
+  RouteAvoidances,
+  ReverseGeocodeResult,
+  PlaceSuggestion,
+  PlaceAutocompleteResult,
+  PlaceDetailsResult,
+  MapsRenderTokenResult,
+} from "@glassly/cloud-protocol";
+
+const DIRECTIONS_PATH = "/api/maps/directions";
+const REVERSE_GEOCODE_PATH = "/api/maps/reverse-geocode";
+const PLACE_AUTOCOMPLETE_PATH = "/api/maps/place-autocomplete";
+const PLACE_DETAILS_PATH = "/api/maps/place-details";
+const RENDER_TOKEN_PATH = "/api/maps/render-token";
+
+export interface MapsDeps {
+  http: HttpClient;
+}
+
+export class Maps {
+  private readonly http: HttpClient;
+
+  constructor(deps: MapsDeps) {
+    this.http = deps.http;
+  }
+
+  /** Compute routes from origin through stops. Primary route first, alternates after. */
+  directions(req: DirectionsRequest): Promise<DirectionsResult> {
+    // Idempotent: a directions request is a pure read, safe to retry on a
+    // transient network failure.
+    return this.http.post<DirectionsResult>(DIRECTIONS_PATH, req, { idempotent: true });
+  }
+
+  /**
+   * Resolve a coordinate to a short road name (`road`) + full formatted address
+   * (`address`). Each is null when none of that kind is found near the coord.
+   */
+  reverseGeocode(coord: LatLng): Promise<ReverseGeocodeResult> {
+    return this.http.post<ReverseGeocodeResult>(REVERSE_GEOCODE_PATH, coord, {
+      idempotent: true,
+    });
+  }
+
+  /**
+   * Type-ahead place search. `sessionToken` groups the keystrokes with the
+   * following `placeDetails` pick into one billed search session.
+   */
+  placeAutocomplete(req: {
+    query: string;
+    near?: LatLng;
+    sessionToken: string;
+  }): Promise<PlaceAutocompleteResult> {
+    // Idempotent: autocomplete is a pure read, safe to retry on a transient blip.
+    return this.http.post<PlaceAutocompleteResult>(PLACE_AUTOCOMPLETE_PATH, req, {
+      idempotent: true,
+    });
+  }
+
+  /** Resolve an autocomplete suggestion (`placeId` + same `sessionToken`) to coordinates. */
+  placeDetails(req: { placeId: string; sessionToken: string }): Promise<PlaceDetailsResult> {
+    return this.http.post<PlaceDetailsResult>(PLACE_DETAILS_PATH, req, {
+      idempotent: true,
+    });
+  }
+
+  /**
+   * The deployment's public client-side render token, for the map consumers
+   * that cannot be proxied (tile rendering, native map SDKs). `token` is null
+   * when the deployment serves none — the caller falls back to requiring a
+   * user-supplied key.
+   */
+  renderToken(): Promise<MapsRenderTokenResult> {
+    return this.http.get<MapsRenderTokenResult>(RENDER_TOKEN_PATH);
+  }
+}