@versionone/agility-sdk 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/index.js

@@ -395,7 +395,7 @@ function parseViolation(message) {
   const rule = parts[1], rest = parts.slice(2).filter((p) => p !== "");
   if (rest[0] === "AttributeDefinition" && rest[1] && rest[2]) return { rule, attribute: `${rest[2]}.${rest[1]}`, tag: rest.join("'") };
   const token = rest.length === 1 && /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9_]*$/.test(rest[0]) ? rest[0] : null;
-  return { rule, attribute: token, tag: rest.length ? rest.join("'") : null };
+  return { rule, attribute: token, tag: !token && rest.length > 1 ? rest.join("'") : null };
 }
 function failuresOf(response) {
   return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => ({
@@ -407,6 +407,7 @@ function failuresOf(response) {
 }
 function outcomeOf(response) {
   return {
+    requestId: typeof response.requestId === "string" && response.requestId ? response.requestId : null,
     created: (response.assetsCreated?.oidTokens ?? []).map(momentless),
     modified: (response.assetsModified?.oidTokens ?? []).map(momentless),
     operated: (response.assetsOperatedOn?.oidTokens ?? []).map(momentless),
@@ -415,13 +416,14 @@ function outcomeOf(response) {
     durationSeconds: typeof response.durationSeconds === "number" ? response.durationSeconds : null
   };
 }
-var emptyOutcome = () => ({ created: [], modified: [], operated: [], failures: [], queryResults: [], durationSeconds: null });
+var emptyOutcome = () => ({ requestId: null, created: [], modified: [], operated: [], failures: [], queryResults: [], durationSeconds: null });
 function mergeOutcome(into, done, offset) {
   into.created.push(...done.created);
   into.modified.push(...done.modified);
   into.operated.push(...done.operated);
   into.failures.push(...done.failures.map((f) => ({ ...f, index: f.index === null ? null : f.index + offset })));
   into.queryResults.push(...done.queryResults);
+  into.requestId = null;
   if (done.durationSeconds !== null) into.durationSeconds = (into.durationSeconds ?? 0) + done.durationSeconds;
   return into;
 }
@@ -1102,6 +1104,65 @@ async function reversible(transport, receipt, options = {}) {
   return { commands, drifted, reactivated };
 }
 
+// src/wire/fields.ts
+var fields_exports = {};
+__export(fields_exports, {
+  visibleFields: () => visibleFields,
+  visibleFieldsByAsset: () => visibleFieldsByAsset
+});
+async function visibleFields(transport, types, scopes) {
+  if (!types.length) return {};
+  const params = [...scopes.map((s) => `scopeOid=${encodeURIComponent(momentless(s))}`), ...types.map((t) => `assetTypeToken=${encodeURIComponent(t)}`)].join("&");
+  const answer = await transport.request({ method: "GET", path: `/api/visibleFields?${params}`, responseType: "json" });
+  if (!Array.isArray(answer)) throw new ApiError("api/visibleFields did not answer a list", 200, "BAD_RESPONSE", answer);
+  const out = {};
+  for (const entry of answer) if (entry && typeof entry.assetType === "string") out[entry.assetType] = Array.isArray(entry.fields) ? entry.fields.filter((f) => typeof f === "string") : [];
+  return out;
+}
+async function visibleFieldsByAsset(transport, oid) {
+  const answer = await transport.request({ method: "GET", path: "/api/visibleFieldsByAsset", query: { oidToken: momentless(oid) }, responseType: "json" });
+  if (!Array.isArray(answer)) throw new ApiError("api/visibleFieldsByAsset did not answer a list", 200, "BAD_RESPONSE", answer);
+  return answer.filter((f) => typeof f === "string");
+}
+
+// src/services/fields.ts
+async function lineage(schema, type) {
+  const out = [];
+  for (let t = type; t && !out.includes(t); ) {
+    out.push(t);
+    const def = await schema.load(t);
+    t = def?.Base;
+  }
+  return out;
+}
+function importantName(token, types) {
+  const dot = token.indexOf(".");
+  if (dot < 0) return token;
+  return types.includes(token.slice(0, dot)) ? token.slice(dot + 1) : null;
+}
+async function describe2(transport, schema, type, scope) {
+  const scopeOid = momentless(scope);
+  const types = await lineage(schema, type);
+  const definition = await schema.load(type);
+  const required = definition ? Object.values(definition.Attributes).filter((a) => a.IsRequired && !a.IsReadOnly).map((a) => a.Name).sort() : [];
+  const [visible, [row]] = await Promise.all([
+    visibleFields(transport, [type], [scopeOid]),
+    query(transport, { from: "Scope", select: [{ from: "Scheme", select: ["ImportantFields", "IsRequiredAtClose"] }], filter: ["ID=$scope"], with: { $scope: scopeOid }, page: { size: 1, start: 0 } }, { lookup: schema })
+  ]);
+  const scheme = row?.Scheme ?? null;
+  const tokens = Array.isArray(scheme?.ImportantFields) ? scheme.ImportantFields.filter((t) => typeof t === "string") : [];
+  const important = [...new Set(tokens.map((t) => importantName(t, types)).filter((n) => !!n))].sort();
+  return {
+    type,
+    scope: scopeOid,
+    scheme: scheme ? momentless(scheme._oid) : null,
+    required,
+    visible: visible[type] ?? [],
+    important,
+    requiredAtClose: scheme?.IsRequiredAtClose === true
+  };
+}
+
 // src/types/asset.ts
 var ASSET_STATE_CODES = { Future: 0, Active: 64, Closed: 128, Dead: 192, Template: 200, OldBrokenDownStory: 208, Deprecated: 254, Deleted: 255 };
 var STATE_OF_CODE = Object.fromEntries(Object.entries(ASSET_STATE_CODES).map(([name, code]) => [code, name]));
@@ -1427,6 +1488,8 @@ __export(rest1_exports, {
   history: () => history,
   list: () => list2,
   momentless: () => momentless,
+  operate: () => operate,
+  template: () => template,
   toQuery: () => toQuery
 });
 var toRef = (doc) => ({ _oid: momentless(doc.idref) });
@@ -1481,6 +1544,19 @@ async function get2(transport, oid, select) {
   const doc = await transport.request({ method: "GET", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { sel: select?.join(",") }, responseType: "json" });
   return fromAssetDocument(doc);
 }
+async function operate(transport, oid, op) {
+  const [type, id] = momentless(oid).split(":");
+  if (!type || !id) throw new UsageError(`"${oid}" is not an OID token (Story:1234)`);
+  const doc = await transport.request({ method: "POST", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { op }, responseType: "json" });
+  if (!doc || typeof doc.id !== "string" || !doc.id) throw new ApiError(`rest-1 ${op} on ${oid} did not answer with an asset`, 200, "BAD_RESPONSE", doc);
+  const moment = doc.id.split(":")[2] ?? null;
+  return { oid: momentless(doc.id), moment };
+}
+async function template(transport, type, options = {}) {
+  const doc = await transport.request({ method: "GET", path: `/rest-1.v1/New/${encodeURIComponent(type)}`, query: { ctx: options.ctx ? momentless(options.ctx) : void 0 }, responseType: "json" });
+  const { _oid: _ignored, ...values } = fromAssetDocument({ ...doc, id: doc.id || `${type}:0` });
+  return values;
+}
 var history = (transport, target, params) => {
   const [type, id] = target.split(":");
   const path = id ? `/rest-1.v1/Hist/${encodeURIComponent(type)}/${encodeURIComponent(id)}` : `/rest-1.v1/Hist/${encodeURIComponent(type)}`;
@@ -1578,16 +1654,39 @@ var AgilityApiClient = class _AgilityApiClient {
     return localize(this.transport, tags, options);
   }
   /**
-   * rest-1.v1, for what query.v1 cannot do: deleted assets (`deleted:
-   * true`), one asset by OID without a page, and history (one row per
-   * moment). Parameters are spelled as a query's (`select`, `filter`).
+   * rest-1.v1, for what the other endpoints cannot do: deleted assets
+   * (`deleted: true`), one asset by OID without a page, history (one row
+   * per moment), a new asset's template (`template`: what the type's
+   * initializer fills in for a context — a Timebox's next name and dates,
+   * a Story's carry-over from a Request), and an operation's result
+   * (`operate`: api/asset performs a Copy but never says what it made;
+   * rest-1 answers the new OID). Parameters are spelled as a query's
+   * (`select`, `filter`).
    */
   data = {
     list: (type, params) => list2(this.transport, type, params),
     get: (oid, select) => get2(this.transport, oid, select),
-    history: (target, params) => history(this.transport, target, params)
+    history: (target, params) => history(this.transport, target, params),
+    template: (type, options) => template(this.transport, type, options),
+    operate: (oid, op) => operate(this.transport, oid, op)
+  };
+  /** Copy an asset (the server's Copy operation) and answer the copy's OID: the one thing api/asset's `execute: "Copy"` does not say. */
+  async copy(oid) {
+    return (await operate(this.transport, oid, "Copy")).oid;
+  }
+  /**
+   * What a form needs for an asset type in a scope: the attributes the
+   * server requires to create one (meta), the ones the product shows there
+   * (api/visibleFields, custom fields included once configured), and the
+   * scope's scheme's important fields and whether they are enforced at
+   * close. `visible` alone answers for several types and scopes at once.
+   */
+  fields = {
+    describe: (type, scope) => describe2(this.transport, this.schema, type, scope),
+    visible: (types, scopes) => visibleFields(this.transport, types, scopes),
+    visibleByAsset: (oid) => visibleFieldsByAsset(this.transport, oid)
   };
-  /** @deprecated since 1.0.0-alpha.3: `client.query` / `client.queries` read through query.v1. Removed in 1.0.0. */
+  /** @deprecated since 1.0.0-alpha.3: use `client.query` / `client.queries` (the same endpoint, query.v1; only the name moved). Removed in 1.0.0. */
   queryV1 = {
     query: (q) => this.query(q),
     queries: (qs) => this.queries(qs)
@@ -1619,7 +1718,7 @@ var AgilityApiClient = class _AgilityApiClient {
       await this.schema.ensureFor(commands);
       return sendGuarded(this.transport, commands, { ...options, lookup: this.schema });
     },
-    /** @deprecated since 1.0.0-alpha.3: use `client.query` (or `client.queryPage` for a total). Removed in 1.0.0. */
+    /** @deprecated since 1.0.0-alpha.3: use `client.query` (rows, through query.v1) or `client.queryPage` (rows and a total, through api/asset as this does). Removed in 1.0.0. */
     query: async (q) => {
       await this.schema.ensureFor([q]);
       return query(this.transport, q, { lookup: this.schema });
@@ -1679,8 +1778,19 @@ var AgilityApiClient = class _AgilityApiClient {
   };
   /** Where a browser opens things on this instance: an asset's page, an attachment's bytes, an embedded image. */
   urls = {
-    /** The asset's page: assetdetail.v1 redirects to the type's own detail page (live 2026-11-12). */
-    asset: (oid) => `${this.config.baseUrl.replace(/\/+$/, "")}/assetdetail.v1?oid=${momentless(oid)}`,
+    /**
+     * The asset's page, from an OID token or an asset Number (S-01001,
+     * what a person typed and what a message shows): assetdetail.v1
+     * resolves either and redirects to the type's own detail page; a signed-
+     * out reader lands there after logging in. Anything else is a UsageError.
+     */
+    asset: (ref) => {
+      const base = this.config.baseUrl.replace(/\/+$/, "");
+      const text = ref.trim();
+      if (isOidToken(text)) return `${base}/assetdetail.v1?oid=${momentless(text)}`;
+      if (isAssetNumber(text)) return `${base}/assetdetail.v1?Number=${encodeURIComponent(text)}`;
+      throw new UsageError(`"${ref}" is neither an OID token (Story:1234) nor an asset number (S-1234)`);
+    },
     attachment: (id) => attachmentUrl(this.config.baseUrl, id),
     embeddedImage: (id) => embeddedImageUrl(this.config.baseUrl, id)
   };
@@ -1708,7 +1818,9 @@ export {
   attachment_exports as attachment,
   createFetchTransport,
   describe as describeBatch,
+  fields_exports as fields,
   guard,
+  importantName,
   isAssetNumber,
   isOidToken,
   kindOf,