@calimero-network/mero-js 27.5.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);
 }
@@ -2046,19 +2066,25 @@ var CalimeroClient = class _CalimeroClient {
   me() {
     return this.get("auth/me");
   }
-  /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-  async addPasskey(passkey) {
+  /**
+   * Add another passkey (another device, `passkey`) to the signed-in account;
+   * answers its credential id. The node asks for the approval of a passkey
+   * the account already has (`412 CONFIRM_REQUIRED`, never the new one),
+   * which `approver` gives.
+   */
+  async addPasskey(passkey, approver) {
     const begin = await this.post("auth/passkeys/add/begin");
     const registration = await passkey.create(begin.options);
-    const { credentialId } = await this.post("auth/passkeys/add/finish", {
-      challengeId: begin.challengeId,
-      registration
-    });
+    const { credentialId } = await this.postConfirmed(
+      "auth/passkeys/add/finish",
+      { challengeId: begin.challengeId, registration },
+      approver
+    );
     return credentialId;
   }
-  /** Remove one of the account's passkeys (not the last). */
-  async removePasskey(credentialId) {
-    await this.delete(`auth/passkeys/${seg(credentialId)}`);
+  /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+  async removePasskey(credentialId, passkey) {
+    await this.deleteConfirmed(`auth/passkeys/${seg(credentialId)}`, passkey);
   }
   /** Name one of the account's passkeys (a device label); `''` clears the name. */
   async labelPasskey(credentialId, label) {
@@ -2086,9 +2112,13 @@ var CalimeroClient = class _CalimeroClient {
   async revokeApiKey(keyId) {
     await this.delete(`auth/apikeys/${seg(keyId)}`);
   }
-  /** Create an API key for an agent or server. The key is returned once. */
-  createApiKey(options) {
-    return this.post("auth/apikeys", options);
+  /**
+   * Create an API key for an agent or server, approved with the account's
+   * `passkey` (`412 CONFIRM_REQUIRED`); needs a passkey session (an API key
+   * is refused `403`). The key is returned once.
+   */
+  createApiKey(options, passkey) {
+    return this.postConfirmed("auth/apikeys", { ...options }, passkey);
   }
   // ---------------------------------------------------------------- apps
   /** Upload a raw WASM bundle (development clusters only); answers its hash. */
@@ -2096,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) {
@@ -2165,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`);
@@ -2196,12 +2262,19 @@ var CalimeroClient = class _CalimeroClient {
   }
   /**
    * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
-   * assertion over the node's challenge (deleting an org, approving a release, ...).
+   * assertion over the node's challenge (deleting an org, approving a release,
+   * adding a member, ...): the same body again, with `confirm`. Without a
+   * passkey (a caller in plain JavaScript passing none) the `412` reaches the
+   * caller as {@link ConfirmRequired}, carrying the challenge.
    */
   postConfirmed(path, body, passkey) {
     return this.confirmed("POST", path, body, passkey);
   }
-  /** {@link postConfirmed} for a DELETE (deleting an organization). */
+  /**
+   * {@link postConfirmed} for a DELETE (deleting an organization, removing a
+   * member or a passkey): `body` (`{}` by default) goes as JSON, and the
+   * confirmed retry carries `confirm` beside it.
+   */
   deleteConfirmed(path, passkey, body = {}) {
     return this.confirmed("DELETE", path, body, passkey);
   }
@@ -2209,7 +2282,7 @@ var CalimeroClient = class _CalimeroClient {
     try {
       return await send(body);
     } catch (error) {
-      if (!(error instanceof ConfirmRequired)) throw error;
+      if (!(error instanceof ConfirmRequired) || !passkey) throw error;
       const d = error.details;
       let assertion;
       try {
@@ -2225,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;
@@ -2533,20 +2612,24 @@ var CalimeroClient = class _CalimeroClient {
   async liftReleaseDeadline(version) {
     await this.delete(`ops/releases/${seg(version)}/deadline`);
   }
-  /** Add a member, or change their role. */
-  async setMember(org, account, role) {
-    await this.post(`orgs/${seg(org)}/members`, { account, role });
+  /** Add a member, or change their role, approved with the caller's `passkey`. */
+  async setMember(org, account, role, passkey) {
+    await this.postConfirmed(`orgs/${seg(org)}/members`, { account, role }, passkey);
   }
-  removeMember(org, account) {
-    return this.delete(`orgs/${seg(org)}/members/${seg(account)}`);
+  /**
+   * Remove a member, or leave (`account` the caller's own), approved with the
+   * caller's `passkey`.
+   */
+  removeMember(org, account, passkey) {
+    return this.deleteConfirmed(`orgs/${seg(org)}/members/${seg(account)}`, passkey);
   }
   /**
    * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
    * for a member of one team (`account` and `team`), or the organization's
-   * default (neither).
+   * default (neither). Approved with the caller's `passkey`.
    */
-  async setCapabilities(org, capabilities, at = {}) {
-    await this.post(`orgs/${seg(org)}/capabilities`, { capabilities, ...at });
+  async setCapabilities(org, capabilities, passkey, at = {}) {
+    await this.postConfirmed(`orgs/${seg(org)}/capabilities`, { capabilities, ...at }, passkey);
   }
   async createTeam(org, name, join, parent) {
     const { teamId } = await this.post(`orgs/${seg(org)}/teams`, { name, join, parent });
@@ -2566,20 +2649,110 @@ var CalimeroClient = class _CalimeroClient {
   async deleteTeam(org, team) {
     await this.delete(`orgs/${seg(org)}/teams/${seg(team)}`);
   }
-  /** Add a member to a team, or change their row: role, lead, capability bits. */
-  async setTeamMember(org, team, account, row = {}) {
-    await this.post(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row });
+  /**
+   * Add a member to a team, or change their row: role, lead, capability bits.
+   * Approved with the caller's `passkey`.
+   */
+  async setTeamMember(org, team, account, passkey, row = {}) {
+    await this.postConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row }, passkey);
   }
-  async removeTeamMember(org, team, account) {
-    await this.delete(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`);
+  /** Remove a member from a team, approved with the caller's `passkey`. */
+  async removeTeamMember(org, team, account, passkey) {
+    await this.deleteConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`, passkey);
   }
-  async invite(org, role, teams = [], options = {}) {
-    const { token } = await this.post(`orgs/${seg(org)}/invites`, { role, teams, ...options });
+  /**
+   * Make an invite into `org` (and `teams`), approved with the caller's
+   * `passkey`; answers its token, which {@link redeemInvite} takes (no
+   * approval there).
+   */
+  async invite(org, role, passkey, teams = [], options = {}) {
+    const { token } = await this.postConfirmed(
+      `orgs/${seg(org)}/invites`,
+      { role, teams, ...options },
+      passkey
+    );
     return token;
   }
   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
@@ -3099,15 +3272,18 @@ export {
   createQuoteVerifier,
   createSealedFetch,
   createSignedReleaseVerifier,
+  deployerKey,
   errorFrom,
   fetchAttestedKey,
   fetchGithubNodeRelease,
   fetchNodeRelease,
   freshCollateral,
   fromB64url,
+  frontendManifest,
   generateOwnerKey,
   orgCapabilities,
   ownerPublicKey,
+  pageDeployment,
   pageQuery,
   pendingApprovalsFrom,
   provisionAgent,