@calimero-network/mero-js 28.0.0 → 28.1.0

package/dist/index.mjs

@@ -1648,6 +1648,26 @@ function upgradeConsent(app, toVersion, returnTo) {
 }
 
 // src/cloud-v2/client.ts
+function deployerKey(deployer) {
+  return "account" in deployer ? `account:${deployer.account}` : `org:${deployer.org}`;
+}
+async function frontendManifest(origin, fetcher = fetch) {
+  const base = origin ?? globalThis.location?.origin;
+  if (!base) throw new Error("no page origin to read the frontend manifest from; pass `origin`");
+  const response = await fetcher(new URL("/.well-known/calimero.json", base).toString());
+  if (!response.ok) throw await refusal(response);
+  const manifest = await response.json();
+  return { ...manifest, deployments: manifest.deployments ?? [] };
+}
+function pageDeployment(href) {
+  const at = href ?? globalThis.location?.href;
+  if (!at) return null;
+  try {
+    return new URL(at).searchParams.get("deployment") || null;
+  } catch {
+    return null;
+  }
+}
 function seg(value) {
   return encodeURIComponent(value);
 }
@@ -2106,14 +2126,41 @@ var CalimeroClient = class _CalimeroClient {
     const { hash } = await this.json("POST", "bundles", void 0, wasm);
     return hash;
   }
-  /** Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex. */
-  uploadBlob(app, data) {
-    return this.json("POST", `apps/${seg(app)}/blobs`, void 0, data);
+  /**
+   * Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex.
+   * `contentType` (default `application/octet-stream`; printable ASCII, the
+   * node refuses another with `400`) is sent as the upload's `Content-Type`:
+   * a component app records it and serves downloads with it. A component
+   * app holding as many blobs as it may answers `429 QUOTA_EXCEEDED`.
+   */
+  uploadBlob(app, data, contentType = {}) {
+    const mime = (typeof contentType === "string" ? contentType : contentType.contentType) ?? "application/octet-stream";
+    return this.json("POST", `apps/${seg(app)}/blobs`, void 0, data, mime);
   }
   /** One of `app`'s blobs, by id (base58 or hex). */
   async downloadBlob(app, id) {
-    const response = await this.send("GET", `apps/${seg(app)}/blobs/${seg(id)}`);
-    return new Uint8Array(await response.arrayBuffer());
+    return (await this.blobContent(app, id)).data;
+  }
+  /**
+   * Download a component app's blob with a grant one of its runs handed out
+   * (`BlobRef::grant`, up to 24 h). No session needed: the grant is the
+   * permission. A bad or expired grant answers `NotFound`, as a missing blob.
+   */
+  async downloadBlobGranted(app, id, grant) {
+    return (await this.blobContent(app, id, { grant })).data;
+  }
+  /**
+   * {@link downloadBlob} (or, with `grant`, {@link downloadBlobGranted}) with
+   * the content type the node serves it as: the uploader's, for a component
+   * app; `application/octet-stream` otherwise.
+   */
+  async blobContent(app, id, options = {}) {
+    const query = options.grant === void 0 ? "" : `?grant=${encodeURIComponent(options.grant)}`;
+    const response = await this.send("GET", `apps/${seg(app)}/blobs/${seg(id)}${query}`);
+    return {
+      data: new Uint8Array(await response.arrayBuffer()),
+      contentType: response.headers.get("content-type") ?? "application/octet-stream"
+    };
   }
   /** `app`'s blobs. */
   async listBlobs(app) {
@@ -2175,6 +2222,15 @@ var CalimeroClient = class _CalimeroClient {
   async setAppMetadata(app, metadata) {
     await this.post(`apps/${seg(app)}/metadata`, { metadata });
   }
+  /**
+   * A component app's xcalls: how many messages wait in its outbox, and the
+   * dead letters (never delivered), newest last. Its owner's or an org
+   * admin's (`403` to anyone else); `409 NOT_SUPPORTED` for an app on the
+   * wasmer runtime, whose xcalls are follow-ups.
+   */
+  appXcalls(app) {
+    return this.get(`apps/${seg(app)}/xcalls`);
+  }
   /** What the app's storage holds: `{ keys, bytes, blobs, blobBytes }`. */
   appStorage(app) {
     return this.get(`apps/${seg(app)}/storage`);
@@ -2242,7 +2298,13 @@ var CalimeroClient = class _CalimeroClient {
   /**
    * Create an app instance from a bundle hash, or from a package release
    * (`{ package, version?, service? }`, installed from the registry first if
-   * the cluster lacks it).
+   * the cluster lacks it). With `deployment`, the instance runs the release
+   * that deployment offers for `package` (`version`, if given, must be it)
+   * and records the deployment; no install, no deployer grant. A package or
+   * version it does not offer answers `400 NOT_OFFERED`, several offered
+   * releases with no `version` `400 VERSION_REQUIRED`, and an unknown
+   * `service` `400 NO_SUCH_SERVICE`. A page opened through `/d/{deployment}/`
+   * finds its deployment with {@link pageDeployment}.
    */
   async createApp(name, bundle, options = {}) {
     const target = typeof bundle === "string" ? { bundle } : bundle;
@@ -2614,6 +2676,83 @@ var CalimeroClient = class _CalimeroClient {
   redeemInvite(token) {
     return this.post(`invites/${seg(token)}/redeem`);
   }
+  // ---------------------------------------------------------------- deployers
+  /**
+   * Let an account or organization install apps where the cluster's
+   * deployments are `granted`, until `until` (RFC 3339 or a `Date`; absent,
+   * the grant does not end). The cluster's owner grants it, approved with
+   * `passkey`, where governance says `deployers: owner`; elsewhere the
+   * operator grants with its key, and this is refused `403`.
+   */
+  grantDeployer(deployer, passkey, options = {}) {
+    const until = options.until instanceof Date ? options.until.toISOString() : options.until;
+    return this.postConfirmed("deployers", { deployer, ...until === void 0 ? {} : { until } }, passkey);
+  }
+  /**
+   * Who may install apps on the cluster: its deployments rule, who grants
+   * deployers, its owner and every grant. For the cluster's owner, or the
+   * operator (its token, `useApiKey`).
+   */
+  deployers() {
+    return this.get("deployers");
+  }
+  /**
+   * End a deployer's grant (`deployer`, or its key `account:{id}` /
+   * `org:{id}`), as the cluster's owner, approved with `passkey`. Apps it
+   * installed, and the apps running them, stay.
+   */
+  async revokeDeployer(deployer, passkey) {
+    const key = typeof deployer === "string" ? deployer : deployerKey(deployer);
+    await this.deleteConfirmed(`deployers/${seg(key)}`, passkey);
+  }
+  // ---------------------------------------------------------------- deployments
+  /**
+   * Create a deployment: `owner`'s (the caller's own account, or an
+   * organization where it holds `MANAGE_APPLICATION` org-wide) list of the
+   * apps it offers, named `name` (1 to 64 characters, one line) for
+   * customers. Approved with `passkey`; where deployments are `granted` the
+   * caller needs a deployer grant. Answers the deployment's id.
+   */
+  async createDeployment(name, owner, passkey) {
+    const { id } = await this.postConfirmed("deployments", { name, owner }, passkey);
+    return id;
+  }
+  /** The deployments the caller manages: its account's, and its organizations' where it holds `MANAGE_APPLICATION`. */
+  async deployments() {
+    const { deployments } = await this.get("deployments");
+    return deployments;
+  }
+  /** A deployment as anyone may read it: its name, its owner's kind and name, and the apps it offers. Public. */
+  deployment(id) {
+    return this.get(`deployments/${seg(id)}`);
+  }
+  /** Delete a deployment that offers nothing and has no instances, approved with `passkey`. */
+  async deleteDeployment(id, passkey) {
+    await this.deleteConfirmed(`deployments/${seg(id)}`, passkey);
+  }
+  /**
+   * Offer `package@version` (installed, and seen by the caller) as `app`
+   * (1 to 64 letters, digits, `.`, `_`, `-`) in deployment `id`, or move an
+   * offered app to another release of its package. Approved with `passkey`.
+   */
+  offerApp(id, offer, passkey) {
+    return this.postConfirmed(`deployments/${seg(id)}/apps`, { ...offer }, passkey);
+  }
+  /**
+   * Withdraw `app` from deployment `id`, approved with `passkey`; refused
+   * while an instance created from the deployment still runs it.
+   */
+  async withdrawApp(id, app, passkey) {
+    await this.deleteConfirmed(`deployments/${seg(id)}/apps/${seg(app)}`, passkey);
+  }
+  /**
+   * The organizations with instances created from deployment `id`, for its
+   * managers: each one's id, name, instance count, apps and releases, and
+   * first instance. Never members, teams or app data.
+   */
+  deploymentOrgs(id) {
+    return this.get(`deployments/${seg(id)}/orgs`);
+  }
 };
 
 // src/cloud-v2/capabilities.ts
@@ -3133,15 +3272,18 @@ export {
   createQuoteVerifier,
   createSealedFetch,
   createSignedReleaseVerifier,
+  deployerKey,
   errorFrom,
   fetchAttestedKey,
   fetchGithubNodeRelease,
   fetchNodeRelease,
   freshCollateral,
   fromB64url,
+  frontendManifest,
   generateOwnerKey,
   orgCapabilities,
   ownerPublicKey,
+  pageDeployment,
   pageQuery,
   pendingApprovalsFrom,
   provisionAgent,