@glassly/cloud-client 0.1.0-dev.99 → 0.2.8-dev.444

package/README.md

@@ -29,6 +29,36 @@ npm install @glassly/cloud-client@dev
 The package ships TypeScript source and targets consumers that compile TS
 themselves (Metro / bundlers / tsc).
 
+## Miniapp store catalog
+
+Host integrations can browse published miniapps through an authenticated
+`CloudClient` instance's `core.store`. This is a Core REST surface; it does
+not require a live runtime session.
+
+```ts
+// `client` is your configured, authenticated CloudClient.
+const {generatedAt, listings} = await client.core.store.list();
+const listing = await client.core.store.get("com.glassly.dashboard");
+if (listing.iconUrl) {
+  const iconBytes = await client.core.store.fetchAsset(listing.iconUrl);
+  // Cache these Uint8Array bytes locally for your UI.
+}
+```
+
+| Method | Returns |
+| --- | --- |
+| `core.store.list()` | `Promise<StoreCatalogResponse>`: `{generatedAt, listings}`; the complete catalog, for local search and tag filtering. |
+| `core.store.get(packageName)` | `Promise<StoreListing>`: one published listing. |
+| `core.store.fetchAsset(url)` | `Promise<Uint8Array>`: authenticated icon/screenshot bytes, accepting a listing URL or a path. |
+
+Listings include identity, tagline, description, tags, author, featured status,
+published version, miniapp type and persistence default, permissions, hardware
+requirements, icon and screenshot URLs, and bundle `{url, sha256, sizeBytes}`.
+Fetch icons and screenshots through `fetchAsset` so Core receives the user's
+Bearer token. The host owns installation, compatibility checks, and updates;
+listing or fetching an asset does not install a miniapp. These APIs belong to
+the host's cloud client, not the miniapp's read-only `session.cloud` module.
+
 ## Part of Glassly
 
 Source lives in the [Glassly monorepo](https://github.com/tetramo-labs/glassly)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassly/cloud-client",
-  "version": "0.1.0-dev.99",
+  "version": "0.2.8-dev.444",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@glassly/cloud-protocol": "0.1.0-dev.99",
+    "@glassly/cloud-protocol": "0.2.8-dev.444",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

package/src/http.ts

@@ -43,6 +43,8 @@ export interface ReqOpts {
 /** The REST surface the modules consume. */
 export interface HttpClient {
   get<T>(path: string, opts?: ReqOpts): Promise<T>;
+  /** GET a binary resource (an image or bundle) as raw bytes. */
+  getBytes(path: string, opts?: ReqOpts): Promise<Uint8Array>;
   head(path: string, opts?: ReqOpts): Promise<Response>;
   post<T>(path: string, body?: unknown, opts?: ReqOpts): Promise<T>;
   postForm<T>(path: string, form: FormData, opts?: ReqOpts): Promise<T>;
@@ -243,6 +245,10 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
     get<T>(path: string, opts?: ReqOpts): Promise<T> {
       return request<T>("GET", path, undefined, opts);
     },
+    async getBytes(path: string, opts?: ReqOpts): Promise<Uint8Array> {
+      const res = await requestRaw("GET", path, undefined, opts);
+      return new Uint8Array(await res.arrayBuffer());
+    },
     head(path: string, opts?: ReqOpts): Promise<Response> {
       return requestRaw("HEAD", path, undefined, opts);
     },

package/src/index.ts

@@ -46,6 +46,11 @@ export type {
   PreinstalledInstallPolicy,
   PreinstalledMiniappRegistry,
   PreinstalledMiniappRegistryEntry,
+  StoreCatalogResponse,
+  StoreListing,
+  StoreListingHardwareRequirement,
+  StoreListingPermission,
+  StoreListingScreenshot,
 } from "./modules/core/core";
 
 export type {

package/src/modules/auth/auth.ts

@@ -65,7 +65,7 @@ export interface AuthModule {
   ): Promise<{ token: string; expiresAt: number }>;
   // Core-owned user/oem identity, read from the Core access token.
   // Runtime-only deployments do not expose this surface.
-  readonly identity: { glasslyUserId: string; tenantId: string };
+  readonly identity: { userId: string; tenantId: string };
   // refresh failed; the host must send the user back through login
   onExpired(handler: () => void): () => void;
 }
@@ -277,14 +277,14 @@ export class Auth implements AuthModule {
    * every call, so the client need not). Throws if no Core access token has been
    * obtained yet, since Core identity is meaningless before the first exchange.
    */
-  get identity(): { glasslyUserId: string; tenantId: string } {
+  get identity(): { userId: string; tenantId: string } {
     this.requireCoreConfig();
     const current = this.store.current();
     if (!current) {
       throw new AuthExpiredError("Core identity is unavailable before first Core sign-in");
     }
     const claims = decodeClaims(current.accessToken);
-    return { glasslyUserId: claims.sub, tenantId: claims.tenant_id };
+    return { userId: claims.sub, tenantId: claims.tenant_id };
   }
 
   /**

package/src/modules/auth/jwt.ts

@@ -3,7 +3,7 @@
  *
  * The client is not a security boundary for its own token: the cloud verifies
  * the signature on every call. So here we only need to read claims the client
- * already trusts (its own `glasslyUserId`, `tenant_id`, and `exp` for the refresh
+ * already trusts (its own `userId`, `tenant_id`, and `exp` for the refresh
  * timing), and we deliberately skip signature checks. Doing a real verification
  * would mean shipping the cloud's public keys to the device, which buys nothing.
  *
@@ -14,7 +14,7 @@
 /**
  * The claims this client reads off an access token.
  *
- * `sub` is the `glasslyUserId`, `tenant_id` is the issuing OEM, and `exp` is the
+ * `sub` is the `userId`, `tenant_id` is the issuing OEM, and `exp` is the
  * Unix-seconds expiry used to decide when to refresh. The index signature keeps
  * the rest of the claims (`sessionId`, `jti`, `aud`, `iss`) accessible without
  * naming each one, since the client only acts on these three.

package/src/modules/core/core.ts

@@ -52,52 +52,55 @@ export type {
 } from "./support-profile";
 
 /**
- * A single miniapp entry as returned by the listing.
+ * One catalog entry from the Glassly Miniapp Store (`GET /api/client/store`).
  *
- * These shapes are owned by miniapp-service, which is not finalized yet, so they
- * are defined here against the spec rather than imported. They are intentionally
- * NOT taken from `@glassly/cloud-protocol`: that package is the live
- * session wire contract (subscriptions, transcripts, the message unions), while
- * a miniapp listing is a core REST resource with no place on the runtime wire.
- * When miniapp-service locks its schema, move these to the shared package and
- * import them here instead.
+ * Mirrors `StoreListing` in Cloud Core's store.service. Defined here rather
+ * than in `@glassly/cloud-protocol` because the catalog is a core REST
+ * resource, not part of the live session wire contract.
  */
-export interface MiniappListing {
-  /** The reverse-DNS identifier, for example "com.example.notes". */
+export interface StoreListing {
   packageName: string;
-  /** Human-readable name shown to the user. */
   name: string;
-  /** The version offered to this user (the latest the user is entitled to). */
+  tagline: string;
+  description: string;
+  tags: string[];
+  featured: boolean;
+  author: { name: string; verified: boolean };
+  /** The active (published) release version. */
   version: string;
-  /** Optional one-line summary for a launcher list. */
+  type: "standard" | "background" | "system_dashboard";
+  persistent: boolean;
+  permissions: StoreListingPermission[];
+  hardwareRequirements: StoreListingHardwareRequirement[];
+  /** Authenticated asset URL; fetch through `core.store.fetchAsset`. */
+  iconUrl: string | null;
+  screenshots: StoreListingScreenshot[];
+  bundle: { url: string; sha256: string; sizeBytes: number };
+  publishedAt: string;
+  updatedAt: string;
+}
+
+export interface StoreListingPermission {
+  type: string;
+  required?: boolean;
   description?: string;
-  /** Optional icon URL for a launcher list. */
-  iconUrl?: string;
 }
 
-/**
- * The manifest that ships inside a miniapp bundle.
- *
- * Same ownership note as `MiniappListing`: this is a miniapp-service shape,
- * defined here against the spec until that schema is locked. The fields below
- * are the minimum the device needs to identify and describe a fetched bundle;
- * miniapp-service is expected to add permission and capability declarations.
- */
-export interface MiniappManifest {
-  packageName: string;
-  name: string;
-  version: string;
-  /** Optional permissions the miniapp declares it needs. */
-  permissions?: string[];
+export interface StoreListingHardwareRequirement {
+  type: string;
+  level: string;
+  description?: string;
 }
 
-/** What `getBundle` resolves to: where to download the bundle, plus its manifest. */
-export interface MiniappBundle {
-  /** A (typically signed, short-lived) URL the device downloads the bundle from. */
-  downloadUrl: string;
-  /** The concrete version resolved, important when the caller omitted `version`. */
-  version: string;
-  manifest: MiniappManifest;
+export interface StoreListingScreenshot {
+  url: string;
+  width: number | null;
+  height: number | null;
+}
+
+export interface StoreCatalogResponse {
+  generatedAt: string;
+  listings: StoreListing[];
 }
 
 export type PreinstalledInstallPolicy =
@@ -129,19 +132,21 @@ export interface CoreDeps {
 }
 
 /**
- * `cloud.core`. Stateless REST grouped by resource (only `miniapps` so far).
+ * `cloud.core`. Stateless REST grouped by resource.
  *
  * The grouping is exposed as a plain object so callers write
- * `cloud.core.miniapps.list()`, matching the public `CoreModule` contract in the
- * spec. Methods are bound in the constructor so destructuring `miniapps` keeps
- * working.
+ * `cloud.core.store.list()`, matching the public `CoreModule` contract in the
+ * spec. Methods are bound in the constructor so destructuring keeps working.
  */
 export class Core {
   readonly miniapps: {
-    list(): Promise<MiniappListing[]>;
-    getBundle(packageName: string, version?: string): Promise<MiniappBundle>;
     getRegistry(opts?: { environment?: string }): Promise<PreinstalledMiniappRegistry>;
   };
+  readonly store: {
+    list(): Promise<StoreCatalogResponse>;
+    get(packageName: string): Promise<StoreListing>;
+    fetchAsset(url: string): Promise<Uint8Array>;
+  };
   readonly reports: {
     submit(input: SubmitReportInput): Promise<SubmitReportResult>;
     addLogs(
@@ -165,34 +170,6 @@ export class Core {
     const supportProfiles = new SupportProfiles(http);
 
     this.miniapps = {
-      /**
-       * List the miniapps available to the authenticated user.
-       *
-       * A GET so it is naturally safe to retry on a transient network error,
-       * which the shared HTTP helper does for us.
-       */
-      list(): Promise<MiniappListing[]> {
-        return http.get<MiniappListing[]>("/api/client/miniapps");
-      },
-
-      /**
-       * Fetch the downloadable bundle for one miniapp.
-       *
-       * When `version` is omitted the cloud resolves the version the user is
-       * entitled to (usually the latest); the resolved value comes back in the
-       * response so the caller can record exactly what it got. The version is
-       * passed as a query parameter and URL-encoded so an unusual version string
-       * cannot break the path.
-       */
-      getBundle(packageName: string, version?: string): Promise<MiniappBundle> {
-        const base = `/api/client/miniapps/${encodeURIComponent(packageName)}/bundle`;
-        const path =
-          version === undefined
-            ? base
-            : `${base}?version=${encodeURIComponent(version)}`;
-        return http.get<MiniappBundle>(path);
-      },
-
       /**
        * Fetch the admin-managed preinstalled miniapp registry for this device.
        *
@@ -206,6 +183,23 @@ export class Core {
         return http.get<PreinstalledMiniappRegistry>(`/api/client/miniapps/registry${query}`);
       },
     };
+    this.store = {
+      /** The whole catalog. Small enough that search and tag filters stay on the device. */
+      list(): Promise<StoreCatalogResponse> {
+        return http.get<StoreCatalogResponse>("/api/client/store");
+      },
+      get(packageName: string): Promise<StoreListing> {
+        return http.get<StoreListing>(`/api/client/store/${encodeURIComponent(packageName)}`);
+      },
+      /**
+       * Icons and screenshots need the user Bearer, which an <Image> cannot
+       * attach. Fetch the bytes here; the host writes them to its file cache.
+       * Accepts the absolute URL from a listing or a bare path.
+       */
+      fetchAsset(url: string): Promise<Uint8Array> {
+        return http.getBytes(toPath(url));
+      },
+    };
     this.reports = {
       submit: reports.submit.bind(reports),
       addLogs: reports.addLogs.bind(reports),
@@ -217,3 +211,10 @@ export class Core {
     };
   }
 }
+
+/** Listings carry absolute asset URLs; the HTTP helper joins paths onto its own base. */
+function toPath(url: string): string {
+  if (!/^https?:\/\//i.test(url)) return url;
+  const parsed = new URL(url);
+  return `${parsed.pathname}${parsed.search}`;
+}