@eluvio/elv-client-js 4.2.30 → 4.2.31

package/src/client/ContentManagement.js

@@ -25,6 +25,34 @@ const {
   ValidatePresence,
 } = require("../Validation");
 
+/* Validation for Fabric tags, groups and query fields */
+
+const ValidateTags = (tags) => {
+  if(!Array.isArray(tags)) {
+    throw Error("Tags must be an array");
+  }
+};
+
+// Group references are content object IDs. A library ID is also accepted, since a library
+// may act as a group (see the Fabric's "lib" unique group type).
+const ValidateGroups = (groups) => {
+  if(!Array.isArray(groups)) {
+    throw Error("Groups must be an array");
+  }
+
+  groups.forEach(groupId => {
+    if(typeof groupId !== "string" || !(groupId.startsWith("iq__") || groupId.startsWith("ilib"))) {
+      throw Error(`Invalid group ID: ${groupId}`);
+    }
+  });
+};
+
+const ValidateQueryFields = (queryFields) => {
+  if(typeof queryFields !== "object" || queryFields === null || Array.isArray(queryFields)) {
+    throw Error("Query fields must be an object");
+  }
+};
+
 exports.SetVisibility = async function({id, visibility}) {
   this.Log(`Setting visibility ${visibility} on ${id}`);
 
@@ -536,14 +564,18 @@ exports.RemoveLibraryContentType = async function({libraryId, typeId, typeName,
  * @namedParams
  * @param {string} libraryId - ID of the library
  * @param {string=} objectId - ID of the object (if contract already exists)
- * @param {Object=} options -
- * type: Version hash of the content type to associate with the object
- *
- * meta: Metadata to use for the new object
- *
- * noEncryptionConk: Set to true to prevent creation of an encryption conk for the object
- *
- * createKMSConk: Set to true to create a KMS conk for object (usually for sharing a playable object) (incompatible with noEncryptionConk: true)
+ * @param {Object=} options - Additional object creation options
+ * @param {string=} options.type - Version hash of the content type to associate with the object
+ * @param {Object=} options.meta - Metadata to use for the new object
+ * @param {string=} options.copy_from - Version hash of an existing object version to copy
+ * @param {string=} options.objectType - System-level object type, e.g. "cgroup" for a content group. May only be
+ * specified when creating a new object - the Fabric rejects an object type change on a new version of an existing object
+ * @param {Array<string>=} options.tags - Fabric tags to associate with the object
+ * @param {Array<string>=} options.groups - IDs of the content groups to add the object to. These categorize content and
+ * are distinct from the access groups that grant permissions
+ * @param {Object<string, string>=} options.queryFields - Unencrypted, indexed query fields to associate with the object
+ * @param {boolean=} options.noEncryptionConk - Set to true to prevent creation of an encryption conk for the object
+ * @param {boolean=} options.createKMSConk - Set to true to create a KMS conk for object (usually for sharing a playable object) (incompatible with noEncryptionConk: true)
  *
  * @returns {Promise<Object>} - Response containing the object ID and write token of the draft, as well as the url of the node that created the write token.
  */
@@ -555,6 +587,10 @@ exports.CreateContentObject = async function({libraryId, objectId, options={}})
 
   if(options.noEncryptionConk && options.createKMSConk) throw new Error("Incompatible options: noEncryptionConk and createKMSConk both set to true");
 
+  if(options.tags !== undefined) { ValidateTags(options.tags); }
+  if(options.groups !== undefined) { ValidateGroups(options.groups); }
+  if(options.queryFields !== undefined) { ValidateQueryFields(options.queryFields); }
+
   // Look up content type, if specified
   let typeId;
   if(options.type) {
@@ -613,7 +649,11 @@ exports.CreateContentObject = async function({libraryId, objectId, options={}})
     body: {      // filter out options not recognized by server (noEncryptionConk, createKMSConk)
       type: options.type,
       meta: options.meta,
-      copy_from: options.copy_from
+      copy_from: options.copy_from,
+      object_type: options.objectType,
+      tags: options.tags,
+      groups: options.groups,
+      query_fields: options.queryFields
     }
   });
 
@@ -1621,3 +1661,320 @@ exports.DeleteWriteToken = async function({writeToken}) {
 
   await this.HttpClient.ClearWriteToken({writeToken});
 };
+
+/* Content group creation, modification, deletion */
+
+/**
+ * Create content tags
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} tags - List of tags
+ *
+ * @returns {Promise<Array<string>>} - The tags on the object after the update
+ */
+exports.AddContentObjectTags = async function({libraryId, writeToken, tags}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidatePresence("tags", tags);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "tags");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Adding tags: ${tags.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "POST",
+    path: path,
+    body: tags,
+    allowFailover: false
+  });
+};
+
+/**
+ * Update content tags, replacing any existing tags
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} tags - Tags the object should have. Must be given explicitly - pass an empty
+ * array to remove all tags
+ *
+ * @returns {Promise<Array<string>>} - The tags on the object after the update
+ */
+exports.SetContentObjectTags = async function({libraryId, writeToken, tags}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidateTags(tags);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "tags");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Updating tags: ${Array.isArray(tags) ? tags.join(", ") : tags}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "PUT",
+    path: path,
+    body: tags,
+    allowFailover: false
+  });
+};
+
+/**
+ * Remove the given tags from a content object
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} tags - List of tags
+ *
+ * @returns {Promise<Array<string>>} - The tags on the object after the update
+ */
+exports.RemoveContentObjectTags = async function({libraryId, writeToken, tags=[]}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidatePresence("tags", tags);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "tags");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Removing tags: ${tags.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "DELETE",
+    path: path,
+    body: tags,
+    allowFailover: false
+  });
+};
+
+/**
+ * Create content query fields
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Object} queryFields - Query fields defined by key/value pairs for each field
+ *
+ * @returns {Promise<Object<string, string>>} - The query fields on the object after the update
+ */
+exports.AddContentObjectQueryFields = async function({libraryId, writeToken, queryFields}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidatePresence("queryFields", queryFields);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "query_fields");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "POST",
+    path: path,
+    body: queryFields,
+    allowFailover: false
+  });
+};
+
+/**
+ * Replace existing content query fields
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Object<string, string>} queryFields - Query fields as key/value pairs. Must be given explicitly -
+ * pass an empty object to remove all fields
+ *
+ * @returns {Promise<Object<string, string>>} - The query fields on the object after the update
+ */
+exports.SetContentObjectQueryFields = async function({libraryId, writeToken, queryFields}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidateQueryFields(queryFields);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "query_fields");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "PUT",
+    path: path,
+    body: queryFields,
+    allowFailover: false
+  });
+};
+
+/**
+ * Remove the given query fields from a content object
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} fieldNames - Names of the query fields to remove
+ *
+ * @returns {Promise<Object<string, string>>} - The query fields on the object after the update
+ */
+exports.RemoveContentObjectQueryFields = async function({libraryId, writeToken, fieldNames=[]}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidatePresence("fieldNames", fieldNames);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "query_fields");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Removing query fields: ${fieldNames.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "DELETE",
+    path: path,
+    body: fieldNames,
+    allowFailover: false
+  });
+};
+
+/**
+ * Create a content group - a content object that other content objects can be associated with in order to
+ * categorize them. Content groups are distinct from the access groups that grant permissions.
+ *
+ * The group is left as a draft; finalize it before adding content objects to it.
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string=} name - Internal content management name of the group
+ * @param {string=} displayTitle - Public-facing title of the group
+ * @param {Array<string>=} tags - Fabric tags to associate with the group
+ * @param {Object<string, string>=} queryFields - Unencrypted, indexed query fields to associate with the group,
+ * as key/value pairs
+ *
+ * @returns {Promise<Object>} - Response containing the object ID and write token of the draft
+ */
+exports.CreateContentGroup = async function({libraryId, name, displayTitle, tags, queryFields}) {
+  ValidateLibrary(libraryId);
+
+  const {objectId, writeToken} = await this.CreateContentObject({
+    libraryId,
+    options: {
+      objectType: "cgroup",
+      meta: {
+        public: {
+          name,
+          asset_metadata: {
+            display_title: displayTitle
+          }
+        }
+      },
+      tags,
+      queryFields
+    }
+  });
+
+  this.Log(`Created content group: ${objectId}`);
+
+  return {
+    objectId,
+    writeToken
+  };
+};
+
+/**
+ * Add a content object to the given content groups. Groups the object already belongs to are retained.
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} groups - IDs of the content groups to add the object to. An empty array is a no-op
+ *
+ * @returns {Promise<Array<string>>} - The groups the object belongs to after the update. Order is not preserved
+ */
+exports.AddContentObjectGroups = async function({libraryId, writeToken, groups=[]}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidateGroups(groups);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "groups");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Adding groups: ${groups.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "POST",
+    path: path,
+    body: groups,
+    allowFailover: false
+  });
+};
+
+/**
+ * Set the content groups a content object belongs to, replacing any existing groups.
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} groups - IDs of the content groups the object should belong to. Must be given
+ * explicitly - pass an empty array to remove the object from all groups
+ *
+ * @returns {Promise<Array<string>>} - The groups the object belongs to after the update. Order is not preserved
+ */
+exports.SetContentObjectGroups = async function({libraryId, writeToken, groups}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidateGroups(groups);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "groups");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Setting groups: ${groups.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "PUT",
+    path: path,
+    body: groups,
+    allowFailover: false
+  });
+};
+
+/**
+ * Remove a content object from the given content groups. Groups not listed are retained, and
+ * removing a group the object does not belong to is a no-op.
+ *
+ * @methodGroup Content Groups
+ * @namedParams
+ * @param {string} libraryId - ID of the library
+ * @param {string} writeToken - Write token of the draft
+ * @param {Array<string>} groups - IDs of the content groups to remove the object from. An empty array is a no-op
+ *
+ * @returns {Promise<Array<string>>} - The groups the object belongs to after the update. Order is not preserved
+ */
+exports.RemoveContentObjectGroups = async function({libraryId, writeToken, groups=[]}) {
+  ValidateLibrary(libraryId);
+  ValidateWriteToken(writeToken);
+  ValidateGroups(groups);
+
+  const path = UrlJoin("qlibs", libraryId, "q", writeToken, "groups");
+  const objectId = this.utils.DecodeWriteToken(writeToken).objectId;
+
+  this.Log(`Removing groups: ${groups.join(", ")}`);
+
+  return this.HttpClient.RequestJsonBody({
+    headers: await this.authClient.AuthorizationHeader({libraryId, objectId, update: true}),
+    method: "DELETE",
+    path: path,
+    body: groups,
+    allowFailover: false
+  });
+};

package/src/client/LiveStream.js

@@ -4215,6 +4215,43 @@ exports.OutputsReset = async function({libraryId, objectId, outputId}) {
   }
 };
 
+/**
+ * Manually switch a live output's active input hop (e.g. primary <-> failover).
+ *
+ * @methodGroup Live Stream
+ * @namedParams
+ * @param {string=} libraryId - Library ID of the output settings object. If not provided, it will be retrieved automatically.
+ * @param {string} objectId - Object ID of the output settings object
+ * @param {string} outputId - ID of the output to switch
+ * @param {number=} hop=0 - Target hop index (0 = primary input, 1 = first failover input)
+ *
+ * @returns {Promise<Object>} - Response from the hop call
+ */
+exports.OutputsHop = async function({libraryId, objectId, outputId, hop=0}) {
+  ValidateObject(objectId);
+  ValidatePresence("outputId", outputId);
+
+  if(!libraryId) {
+    libraryId = await this.ContentObjectLibraryId({objectId});
+  }
+
+  // Route to a live egress node, then to the specific output's node
+  const {restore} = await RouteToLiveEgress({client: this});
+  await RouteToOutputNode({client: this, libraryId, objectId, outputId});
+
+  try {
+    return await this.CallBitcodeMethod({
+      libraryId,
+      objectId,
+      method: UrlJoin("live", "outputs", outputId, "ctrl", "hop"),
+      queryParams: {hop},
+      constant: false
+    });
+  } finally {
+    restore();
+  }
+};
+
 /**
  * Delete a live output.
  *

package/testScripts/Test.js

@@ -11,7 +11,7 @@ const Test = async () => {
 
   try {
     const client = await ElvClient.FromNetworkName({
-      networkName: "demo"
+      networkName: "main"
     });
 
     const wallet = client.GenerateWallet();
@@ -21,7 +21,19 @@ const Test = async () => {
 
     client.SetSigner({signer});
 
-    console.log(await client.ContentLibraries());
+    const configUrl = new URL(await client.ConfigUrl());
+    configUrl.pathname = "/config";
+    // if(geo) { configUrl.searchParams.set("elvgeo", geo); }   // optional region scoping
+
+    const fabricInfo = await (await fetch(configUrl.toString())).json();
+    // fabricInfo.network.services.*  e.g. live_egress, ethereum, authority, etc.
+    const liveEgressUrls = fabricInfo?.network?.services?.live_egress;
+    console.log('fabricINfo', fabricInfo.network?.services?.tenant_query)
+
+    // tenant_query nodes are now wired into the client and used automatically by TenantContent:
+    console.log('client tenantQueryURIs', client.Nodes().tenantQueryURIs)
+    // const result = await client.TenantContent({limit: 5});
+    // console.log(JSON.stringify(result, null, 2));
   } catch(error) {
     console.error(error);
     console.error(JSON.stringify(error, null, 2));

package/utilities/ObjectInfo.js

@@ -0,0 +1,99 @@
+// List all info for an object: details, profile, tags, content groups and query fields
+
+const R = require("ramda");
+
+const {NewOpt} = require("./lib/options");
+
+const Utility = require("./lib/Utility");
+
+const Client = require("./lib/concerns/Client");
+const ExistObjOrVer = require("./lib/concerns/ExistObjOrVer");
+const ArgOutfile = require("./lib/concerns/ArgOutfile");
+
+// Sections that come from the Fabric's tags/groups/query_fields endpoints. A node that does not
+// serve them should not prevent the rest of the info from being reported.
+const FABRIC_PROPERTIES = [
+  {key: "tags", method: "ContentObjectTags", empty: []},
+  {key: "groups", method: "ContentObjectGroups", empty: []},
+  {key: "query_fields", method: "ContentObjectQueryFields", empty: {}}
+];
+
+class ObjectInfo extends Utility {
+  blueprint() {
+    return {
+      concerns: [Client, ExistObjOrVer, ArgOutfile],
+      options: [
+        NewOpt("details", {
+          descTemplate: "Include object details (id, hash, type, size stats). Default: true",
+          default: true,
+          type: "boolean"
+        }),
+        NewOpt("profile", {
+          descTemplate: "Include the content profile (owner, visibility, status code, KMS, tenant). Default: true",
+          default: true,
+          type: "boolean"
+        }),
+        NewOpt("properties", {
+          descTemplate: "Include Fabric tags, content groups and query fields. Default: true",
+          default: true,
+          type: "boolean"
+        })
+      ]
+    };
+  }
+
+  async body() {
+    const logger = this.logger;
+    const client = await this.concerns.Client.get();
+
+    const {libraryId, objectId, versionHash} = await this.concerns.ExistObjOrVer.argsProc();
+
+    const info = {
+      object_id: objectId,
+      version_hash: versionHash,
+      library_id: libraryId
+    };
+
+    if(this.args.details || this.args.profile) {
+      // ContentObject requests details and profile together
+      const contentObject = await client.ContentObject({objectId, versionHash});
+
+      if(this.args.profile) {
+        info.profile = contentObject.content_profile;
+      }
+
+      if(this.args.details) {
+        info.details = R.omit(["content_profile"], contentObject);
+      }
+    }
+
+    if(this.args.properties) {
+      for(const {key, method, empty} of FABRIC_PROPERTIES) {
+        try {
+          info[key] = await client[method]({objectId, versionHash}) || empty;
+        } catch(error) {
+          logger.warn(`Unable to retrieve ${key}: ${error.message || error}`);
+          info[key] = {error: error.message || String(error)};
+        }
+      }
+    }
+
+    logger.data("object_info", info);
+
+    if(this.args.outfile) {
+      this.concerns.ArgOutfile.writeJson({obj: info});
+    } else {
+      logger.logObject(info);
+    }
+  }
+
+  header() {
+    return `Get info for object ${this.args.versionHash || this.args.objectId}`;
+  }
+}
+
+if(require.main === module) {
+  Utility.cmdLineInvoke(ObjectInfo);
+} else {
+  module.exports = ObjectInfo;
+}