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

package/dist/index.d.cts

@@ -11,7 +11,8 @@
  *   aborted         the caller's signal ended it
  *   commandFailure  api/asset answered 200 with failed commands inside (CommandFailureError)
  *   protocol        the server answered something the SDK cannot read
- *   usage           a mistake caught before any request (UsageError): fix the call
+ *   usage           a mistake caught before any request (UsageError): nothing was sent, so
+ *                   do not blame the server — fix the call (status is 0 here)
  *   unknown         none of the above
  */
 type ErrorKind = "auth" | "forbidden" | "notFound" | "invalid" | "transient" | "aborted" | "commandFailure" | "protocol" | "usage" | "unknown";
@@ -74,7 +75,7 @@ interface RequestOptions {
     /**
      * Called with a successful response's status and headers before its body
      * is read — for what the body alone does not say (an attachment's
-     * Content-Type, say). A transport that cannot see headers may skip it.
+     * Content-Type, an ETag). A transport that cannot see headers may skip it.
      */
     onResponse?: (response: {
         status: number;
@@ -82,6 +83,12 @@ interface RequestOptions {
             get(name: string): string | null;
         };
     }) => void;
+    /**
+     * The request is conditional (an If-None-Match header is set) and a
+     * 304 Not Modified is an answer, not a failure: the promise then resolves
+     * to undefined after onResponse has seen the 304 and its headers.
+     */
+    acceptNotModified?: boolean;
 }
 interface Transport {
     request<T>(options: RequestOptions): Promise<T>;
@@ -98,7 +105,9 @@ interface Transport {
  * failure from an answer, but they are narrow on purpose: only requests the
  * caller marks idempotent (every GET is; a POST to api/asset is not — a
  * retried batch write after a timeout is a double write), and only on a
- * network error or a 5xx. A 4xx is an answer and is never retried.
+ * network error, a 5xx, or a 429 (the instance throttles per token; it
+ * sends no Retry-After, but one is honoured when present, up to 30 s). Any
+ * other 4xx is an answer and is never retried.
  */
 interface FetchTransportConfig {
     baseUrl: string;
@@ -114,7 +123,12 @@ interface FetchTransportConfig {
      * timeouts that turn into retries.
      */
     timeoutMs?: number;
-    /** Extra attempts after the first, for idempotent requests only. Default 0. */
+    /**
+     * Extra attempts after the first, for idempotent requests only (a GET,
+     * a query.v1 read, a guarded batch that says so), after a network
+     * failure or a 5xx. Default 1: one resend, 150 ms later. 0 turns it off.
+     * A plain write is never resent whatever this says.
+     */
     retries?: number;
     fetchImpl?: typeof fetch;
     /**
@@ -4286,7 +4300,13 @@ declare function fromWireRow<Row extends Asset = Asset>(row: Record<string, unkn
 interface CommandFailureDetail {
     index: number | null;
     message: string;
-    echoed: Record<string, unknown>;
+    /**
+     * The command as the server echoed it, under a generated alias: what a
+     * caller resends after correcting it. Readable on every failure but not
+     * enumerable, so a serialised failure (a receipt, a log line) carries
+     * index, message and violation and not the whole command.
+     */
+    readonly echoed: Record<string, unknown>;
     /** The message read as a validation violation, when it is one. */
     violation: Violation | null;
 }
@@ -4302,7 +4322,7 @@ interface Violation {
     rule: string;
     /** "Story.Scope" when the violation names an attribute; null otherwise. */
     attribute: AttributeTokenRef | null;
-    /** The loc-2 tag naming what was violated, when the message carries one. */
+    /** The loc-2 tag naming what was violated (`AttributeDefinition'Scope'Story`), when the message carries one; null for the token spelling. */
     tag: string | null;
 }
 /** The violation a failure message describes, or null when it is not one. */
@@ -4311,6 +4331,8 @@ declare function parseViolation(message: string): Violation | null;
 declare function failuresOf<Row extends Asset = Asset>(response: AssetApiResponse<Row>): CommandFailureDetail[];
 /** What a batch did, in the model's terms: the services read this, never the envelope. */
 interface Outcome<Row extends Asset = Asset> {
+    /** The server's id for the request: what to quote when asking about a batch. Null for an outcome merged from several sends. */
+    requestId: string | null;
     created: Oid[];
     modified: Oid[];
     operated: Oid[];
@@ -4319,7 +4341,12 @@ interface Outcome<Row extends Asset = Asset> {
     queryResults: (Row[] | null)[];
     durationSeconds: number | null;
 }
-/** The outcome of a (translated) response: OIDs momentless, failures normalised. */
+/**
+ * The outcome of a (translated) response: OIDs momentless, failures
+ * normalised. Every field has a default, so a partial envelope (a test fake
+ * that sends only queryResult) still yields a complete Outcome; consumers'
+ * fakes rely on that, and the unit tests keep it so.
+ */
 declare function outcomeOf<Row extends Asset = Asset>(response: AssetApiResponse<Row>): Outcome<Row>;
 /** An outcome with nothing in it, to merge several sends into. */
 declare const emptyOutcome: <Row extends Asset = Asset>() => Outcome<Row>;
@@ -4536,6 +4563,10 @@ declare class TypeCache {
     /** Loaded types; null records that the instance has no such type, so it is not asked for again. */
     readonly types: Map<string, AssetType | null>;
     readonly loading: Map<string, Promise<AssetType | null>>;
+    /** The schema's tag the loaded types came with (meta.v1's ETag, one for the whole schema); null until a load, or for a seeded cache. */
+    etag: string | null;
+    /** Forget every loaded type (and the tag): the next query loads afresh. In-flight loads finish into the cache as before. */
+    clear(): void;
     /** A cache seeded from a metamodel document. */
     static fromMetamodel(metamodel: Metamodel): TypeCache;
 }
@@ -4568,6 +4599,18 @@ declare class Schema implements AttributeLookup {
      * any other failure (auth, network) is thrown, not swallowed.
      */
     load(token: AssetTypeToken): Promise<AssetType | null>;
+    /**
+     * Has the instance's schema changed since these types were loaded? One
+     * small conditional read of meta.v1. Unchanged: nothing happens.
+     * Changed (or never tagged, or the transport cannot see headers): the
+     * loaded types are dropped, so the next query loads them again, and the
+     * new tag is kept. Answers whether it changed and the current tag. A
+     * schema without a transport (seeded) never changes.
+     */
+    revalidate(): Promise<{
+        changed: boolean;
+        etag: string | null;
+    }>;
     /**
      * Load whatever the queries in a batch need to have their rows translated:
      * the `from` types, then the types behind every relation hop and sub-select,
@@ -4773,6 +4816,40 @@ declare function reversible(transport: Transport, receipt: Pick<Receipt, "revers
     reactivated: Oid[];
 }>;
 
+/**
+ * The fields service: what a form for an asset type in a scope needs to
+ * know, from three sources the API keeps apart —
+ *   - meta.v1 (through the schema): which attributes are REQUIRED to
+ *     create one (IsRequired and writable: Name and Scope on a Story);
+ *   - api/visibleFields: which attributes the product SHOWS for the type
+ *     in that scope, custom fields included once configured;
+ *   - the scope's Scheme: its IMPORTANT fields (Scheme.ImportantFields, a
+ *     list of attribute tokens) and whether they are enforced at close
+ *     (Scheme.IsRequiredAtClose).
+ * One call, one answer, every list spelled as bare attribute names.
+ */
+
+interface FieldsOf {
+    type: AssetTypeToken;
+    scope: Oid;
+    /** The scope's Scheme; null when the scope has none. */
+    scheme: Oid | null;
+    /** Attributes the server requires on a create (meta: IsRequired, writable). */
+    required: string[];
+    /** Attributes the product shows for the type in this scope (api/visibleFields). */
+    visible: string[];
+    /** The scheme's important fields that belong to this type (or an ancestor); [] when the scheme names none. */
+    important: string[];
+    /** Whether the scheme enforces its important fields when an asset is closed. */
+    requiredAtClose: boolean;
+}
+/**
+ * An important-field token as the scheme spells it ("Story.Owners", or a
+ * bare "Owners") reduced to the attribute name when it belongs to one of
+ * the types given; null otherwise.
+ */
+declare function importantName(token: string, types: readonly AssetTypeToken[]): string | null;
+
 /**
  * The guard: an api/asset batch sent as a compare-and-set, so a change only
  * lands on an asset nobody else has changed since it was read. Ported from
@@ -4938,6 +5015,108 @@ declare namespace loc2 {
   export type { loc2_Localizations as Localizations, loc2_LocalizeOptions as LocalizeOptions };
 }
 
+interface TokenRef {
+    href: string;
+    tokenref: AttributeTokenRef;
+}
+interface NameRef {
+    href: string;
+    nameref: AssetTypeToken;
+}
+interface AttributeDefinitionDocument {
+    HREF?: string;
+    _type: "AttributeDefinition";
+    Name: string;
+    Token: AttributeTokenRef;
+    DisplayName: string;
+    AttributeType: AttributeType;
+    IsReadOnly: boolean;
+    IsRequired: boolean;
+    IsMultivalue: boolean;
+    IsCanned: boolean;
+    IsCustom: boolean;
+    /** Present on an inherited attribute: the defining ancestor's attribute. */
+    Base?: TokenRef;
+    ReciprocalRelation?: TokenRef;
+    OrderByAttribute?: TokenRef;
+    DisplayByAttribute?: TokenRef;
+    /** Present on a Relation. */
+    RelatedAsset?: NameRef;
+}
+interface AssetTypeDocument {
+    HREF?: string;
+    Version?: string;
+    _type: "AssetType";
+    Token: AssetTypeToken;
+    /** The delivered Name is a reference to the type's Name attribute; the token is the name. */
+    Name: TokenRef | string;
+    DisplayName: string;
+    Abstract: boolean;
+    /** Absent on a root type. */
+    Base?: NameRef;
+    DefaultOrderBy?: TokenRef;
+    DefaultDisplayBy?: TokenRef;
+    ShortName?: TokenRef;
+    Description?: TokenRef;
+    Attributes: Record<string, AttributeDefinitionDocument>;
+    Operations?: Record<string, unknown>;
+    Rules?: Record<string, unknown>;
+}
+interface MetamodelDocument {
+    HREF?: string;
+    Version: string;
+    AssetTypes: Record<string, AssetTypeDocument>;
+}
+declare function toAttributeDefinition(doc: AttributeDefinitionDocument): AttributeDefinition;
+declare function toAssetType(doc: AssetTypeDocument): AssetType;
+declare function toMetamodel(doc: MetamodelDocument): Metamodel;
+/** Is this a metamodel document as meta.v1 delivers it? (A downloaded metamodel.json, say.) */
+declare function isMetamodelDocument(value: unknown): value is MetamodelDocument;
+/** A conditional read: the tag a previous answer carried. With it, an unchanged resource is null. */
+interface ConditionalOptions {
+    ifNoneMatch?: string | null;
+}
+/** What a read answered, with the schema's tag as the server sent it (null when it sent none). */
+interface Tagged<T> {
+    value: T;
+    etag: string | null;
+}
+declare function getMetamodel(transport: Transport): Promise<Metamodel>;
+/** The metamodel with its tag; null when `ifNoneMatch` still matches (nothing was downloaded). */
+declare function readMetamodel(transport: Transport, options?: ConditionalOptions): Promise<Tagged<Metamodel> | null>;
+declare function getAssetType(transport: Transport, token: AssetTypeToken): Promise<AssetType>;
+/** One type with the schema's tag; null when `ifNoneMatch` still matches. */
+declare function readAssetType(transport: Transport, token: AssetTypeToken, options?: ConditionalOptions): Promise<Tagged<AssetType> | null>;
+/**
+ * The schema's current tag, from one small read, or null when the server
+ * sends none. With `ifNoneMatch`, "unchanged" is answered as that same tag
+ * without a body — the cheapest way to ask whether anything in meta moved.
+ */
+declare function etag(transport: Transport, options?: ConditionalOptions): Promise<string | null>;
+declare function getAttributeDefinition(transport: Transport, tokenref: AttributeTokenRef): Promise<AttributeDefinition>;
+
+type meta_AssetTypeDocument = AssetTypeDocument;
+type meta_AttributeDefinitionDocument = AttributeDefinitionDocument;
+type meta_ConditionalOptions = ConditionalOptions;
+type meta_MetamodelDocument = MetamodelDocument;
+type meta_NameRef = NameRef;
+type meta_Tagged<T> = Tagged<T>;
+type meta_TokenRef = TokenRef;
+declare const meta_etag: typeof etag;
+declare const meta_getAssetType: typeof getAssetType;
+declare const meta_getAttributeDefinition: typeof getAttributeDefinition;
+declare const meta_getMetamodel: typeof getMetamodel;
+declare const meta_isMetamodelDocument: typeof isMetamodelDocument;
+declare const meta_readAssetType: typeof readAssetType;
+declare const meta_readMetamodel: typeof readMetamodel;
+declare const meta_toAssetType: typeof toAssetType;
+declare const meta_toAttributeDefinition: typeof toAttributeDefinition;
+declare const meta_toMetamodel: typeof toMetamodel;
+declare namespace meta {
+  export { meta_etag as etag, meta_getAssetType as getAssetType, meta_getAttributeDefinition as getAttributeDefinition, meta_getMetamodel as getMetamodel, meta_isMetamodelDocument as isMetamodelDocument, meta_readAssetType as readAssetType, meta_readMetamodel as readMetamodel, meta_toAssetType as toAssetType, meta_toAttributeDefinition as toAttributeDefinition, meta_toMetamodel as toMetamodel };
+  export type { meta_AssetTypeDocument as AssetTypeDocument, meta_AttributeDefinitionDocument as AttributeDefinitionDocument, meta_ConditionalOptions as ConditionalOptions, meta_MetamodelDocument as MetamodelDocument, meta_NameRef as NameRef, meta_Tagged as Tagged, meta_TokenRef as TokenRef };
+}
+
 interface AssetRefDocument {
     _type: "Asset";
     href: string;
@@ -5012,6 +5191,33 @@ interface ReadResult<Row extends Asset = Asset> {
 declare const list: <Row extends Asset = Asset>(transport: Transport, type: string, params: ReadParams) => Promise<ReadResult<Row>>;
 /** One asset by OID. */
 declare function get<Row extends Asset = Asset>(transport: Transport, oid: Oid, select?: string[]): Promise<Row>;
+/**
+ * What an operation answered with: the asset the server returned, as an
+ * OID token — for Copy the copy, for anything else the operated asset —
+ * and the moment the server stamped on it.
+ */
+interface OperationResult {
+    oid: Oid;
+    moment: string | null;
+}
+/**
+ * Run an operation (Copy, Inactivate, …) through rest-1, for its result.
+ * api/asset's `execute` performs the same operations but reports only the
+ * operated asset, so a Copy's new OID is unobservable there; rest-1 answers
+ * it. Not idempotent: never retried.
+ */
+declare function operate(transport: Transport, oid: Oid, op: string): Promise<OperationResult>;
+/** A new asset's template as the model carries it: the attributes the initializer set, no `_oid`. */
+type Template<Row extends Asset = Asset> = Partial<Omit<Row, "_oid">>;
+/**
+ * The template for a new asset of `type` in a context (a Scope, a parent
+ * asset): what the server's initializer would fill in — defaults nothing
+ * else exposes. Idempotent, like any GET. Without a context the template
+ * is empty, and an unknown context is echoed back, not refused.
+ */
+declare function template<Row extends Asset = Asset>(transport: Transport, type: string, options?: {
+    ctx?: Oid;
+}): Promise<Template<Row>>;
 /** A bounded history read: one row per moment, _oid carrying the moment. */
 declare const history: <Row extends Asset = Asset>(transport: Transport, target: string, params: ReadParams) => Promise<ReadResult<Row>>;
 
@@ -5019,18 +5225,22 @@ type rest1_AssetDocument = AssetDocument;
 type rest1_AssetRefDocument = AssetRefDocument;
 type rest1_AssetsDocument = AssetsDocument;
 type rest1_AttributeDocument = AttributeDocument;
+type rest1_OperationResult = OperationResult;
 type rest1_ReadParams = ReadParams;
 type rest1_ReadResult<Row extends Asset = Asset> = ReadResult<Row>;
 type rest1_RelationDocument = RelationDocument;
+type rest1_Template<Row extends Asset = Asset> = Template<Row>;
 declare const rest1_fromAssetDocument: typeof fromAssetDocument;
 declare const rest1_get: typeof get;
 declare const rest1_history: typeof history;
 declare const rest1_list: typeof list;
 declare const rest1_momentless: typeof momentless;
+declare const rest1_operate: typeof operate;
+declare const rest1_template: typeof template;
 declare const rest1_toQuery: typeof toQuery;
 declare namespace rest1 {
-  export { rest1_fromAssetDocument as fromAssetDocument, rest1_get as get, rest1_history as history, rest1_list as list, rest1_momentless as momentless, rest1_toQuery as toQuery };
-  export type { rest1_AssetDocument as AssetDocument, rest1_AssetRefDocument as AssetRefDocument, rest1_AssetsDocument as AssetsDocument, rest1_AttributeDocument as AttributeDocument, rest1_ReadParams as ReadParams, rest1_ReadResult as ReadResult, rest1_RelationDocument as RelationDocument };
+  export { rest1_fromAssetDocument as fromAssetDocument, rest1_get as get, rest1_history as history, rest1_list as list, rest1_momentless as momentless, rest1_operate as operate, rest1_template as template, rest1_toQuery as toQuery };
+  export type { rest1_AssetDocument as AssetDocument, rest1_AssetRefDocument as AssetRefDocument, rest1_AssetsDocument as AssetsDocument, rest1_AttributeDocument as AttributeDocument, rest1_OperationResult as OperationResult, rest1_ReadParams as ReadParams, rest1_ReadResult as ReadResult, rest1_RelationDocument as RelationDocument, rest1_Template as Template };
 }
 
 interface ClientOptions {
@@ -5076,12 +5286,15 @@ type Me = Pick<Member, "_oid" | "Name" | "Username" | "Nickname" | "Email">;
  * every write answers in the model's terms (an Outcome, never an envelope).
  *
  * Reads: `query`, `queries`, `get`, `queryPage`, `pages`, `all`, `me`. A
- * query body is the same everywhere; the client picks the endpoint
- * (query.v1 for plain reads — read-only by construction, so a request can
- * be retried like a GET; api/asset where a total is wanted; rest-1 behind
- * `data` for deleted assets and history). Writes: `assets.send`,
- * `assets.sendGuarded`, `batch.run`. Services: `resolve`, `attachments`,
- * `embeddedImages`, `schema`, `localize`, `urls`.
+ * query body is the same everywhere; the client picks the endpoint.
+ * query.v1 answers rows alone — the lightest response, and read-only by
+ * construction, so a request can be resent like a GET — but its shape has
+ * nowhere to put a total; api/asset reports one (`needTotal`) beside the
+ * rows, which is why `queryPage` goes there and `query` does not. rest-1
+ * sits behind `data` for what neither does: deleted assets, history, a
+ * new asset's template, an operation's result. Writes: `assets.send`,
+ * `assets.sendGuarded`, `batch.run`, `copy`. Services: `resolve`,
+ * `fields`, `attachments`, `embeddedImages`, `schema`, `localize`, `urls`.
  */
 declare class AgilityApiClient {
     readonly transport: Transport;
@@ -5097,9 +5310,12 @@ declare class AgilityApiClient {
     withSignal(signal: AbortSignal): AgilityApiClient;
     /**
      * One query, its rows, translated. Sent to query.v1: it cannot write, so
-     * the request is retried like a GET after a network failure or a 5xx. A
-     * page is required; a query the server refuses throws (kind "invalid"),
-     * never an empty result.
+     * the request is marked idempotent and the transport may resend it after
+     * a network failure or a 5xx — when `retries` is set above its default
+     * of 0. A page is required; a query the server refuses throws an
+     * ApiError (kind "invalid", code QUERY_REJECTED; `message` holds the
+     * server's sentences, `details` its whole error document), never an
+     * empty result.
      */
     query<const F extends From, const Q extends QueryBody<F>>(q: Q & QueryBody<F>): Promise<RowOf<Q>[]>;
     query<Row extends Asset = Asset>(q: QueryBody): Promise<Row[]>;
@@ -5134,11 +5350,21 @@ declare class AgilityApiClient {
     all<Row extends Asset = Asset>(q: QueryBody, options?: PagesOptions): Promise<Row[]>;
     /** The member these credentials belong to (Member.IsSelf, live 2026-11-12): what a comment's Author is. */
     me(): Promise<Me>;
-    /** meta.v1: the instance's schema, raw. (The translated, cached view is `schema`.) */
+    /**
+     * meta.v1: the instance's schema, raw. (The translated, cached view is
+     * `schema`; `schema.revalidate()` drops it when the schema's tag moves.)
+     * `read` and `readType` are conditional: pass the tag a previous answer
+     * carried and an unchanged schema answers null without a download —
+     * meta.v1 sends one strong ETag for the whole schema. `etag()` reads that
+     * tag alone, from the smallest resource.
+     */
     readonly meta: {
         metamodel: () => Promise<Metamodel>;
+        read: (options?: ConditionalOptions) => Promise<Tagged<Metamodel> | null>;
         assetType: (token: string) => Promise<AssetType>;
+        readType: (token: string, options?: ConditionalOptions) => Promise<Tagged<AssetType> | null>;
         attributeDefinition: (tokenref: `${string}.${string}`) => Promise<AttributeDefinition>;
+        etag: (options?: ConditionalOptions) => Promise<string | null>;
     };
     /**
      * loc-2.v1: labels for tags, in one request (meta's DisplayName values are
@@ -5147,16 +5373,39 @@ declare class AgilityApiClient {
      */
     localize(tags: readonly string[], options?: LocalizeOptions): Promise<Localizations>;
     /**
-     * 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`).
      */
     readonly data: {
         list: <Row extends Asset = Asset>(type: string, params: ReadParams) => Promise<ReadResult<Row>>;
         get: <Row extends Asset = Asset>(oid: string, select?: string[]) => Promise<Row>;
         history: <Row extends Asset = Asset>(target: string, params: ReadParams) => Promise<ReadResult<Row>>;
+        template: <F extends From>(type: F, options?: {
+            ctx?: Oid;
+        }) => Promise<Partial<Omit<TypeOf<F>, "_oid">>>;
+        operate: (oid: Oid, op: string) => Promise<OperationResult>;
     };
-    /** @deprecated since 1.0.0-alpha.3: `client.query` / `client.queries` read through query.v1. Removed in 1.0.0. */
+    /** 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. */
+    copy(oid: Oid): Promise<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.
+     */
+    readonly fields: {
+        describe: (type: From, scope: Oid) => Promise<FieldsOf>;
+        visible: (types: readonly From[], scopes: readonly Oid[]) => Promise<Record<string, string[]>>;
+        visibleByAsset: (oid: Oid) => Promise<string[]>;
+    };
+    /** @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. */
     readonly queryV1: {
         query: <Row extends Asset = Asset>(q: QueryBody) => Promise<Row[]>;
         queries: <Row extends Asset = Asset>(qs: QueryBody[]) => Promise<Row[][]>;
@@ -5181,7 +5430,7 @@ declare class AgilityApiClient {
          * cover.
          */
         sendGuarded: <Row extends Asset = Asset>(commands: Command[], options?: Pick<SendOptions, "throwOnFailure">) => Promise<GuardedResult<Row>>;
-        /** @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: <Row extends Asset = Asset>(q: QueryBody) => Promise<Row[]>;
         /** @deprecated since 1.0.0-alpha.3: use `client.queries`. Removed in 1.0.0. */
         queries: <Row extends Asset = Asset>(qs: QueryBody[]) => Promise<Row[][]>;
@@ -5265,91 +5514,23 @@ declare class AgilityApiClient {
     };
     /** Where a browser opens things on this instance: an asset's page, an attachment's bytes, an embedded image. */
     readonly urls: {
-        /** The asset's page: assetdetail.v1 redirects to the type's own detail page (live 2026-11-12). */
-        asset: (oid: Oid) => string;
+        /**
+         * 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: Oid | string) => string;
         attachment: (id: string | number) => string;
         embeddedImage: (id: string | number) => string;
     };
 }
 
-interface TokenRef {
-    href: string;
-    tokenref: AttributeTokenRef;
-}
-interface NameRef {
-    href: string;
-    nameref: AssetTypeToken;
-}
-interface AttributeDefinitionDocument {
-    HREF?: string;
-    _type: "AttributeDefinition";
-    Name: string;
-    Token: AttributeTokenRef;
-    DisplayName: string;
-    AttributeType: AttributeType;
-    IsReadOnly: boolean;
-    IsRequired: boolean;
-    IsMultivalue: boolean;
-    IsCanned: boolean;
-    IsCustom: boolean;
-    /** Present on an inherited attribute: the defining ancestor's attribute. */
-    Base?: TokenRef;
-    ReciprocalRelation?: TokenRef;
-    OrderByAttribute?: TokenRef;
-    DisplayByAttribute?: TokenRef;
-    /** Present on a Relation. */
-    RelatedAsset?: NameRef;
-}
-interface AssetTypeDocument {
-    HREF?: string;
-    Version?: string;
-    _type: "AssetType";
-    Token: AssetTypeToken;
-    /** The delivered Name is a reference to the type's Name attribute; the token is the name. */
-    Name: TokenRef | string;
-    DisplayName: string;
-    Abstract: boolean;
-    /** Absent on a root type. */
-    Base?: NameRef;
-    DefaultOrderBy?: TokenRef;
-    DefaultDisplayBy?: TokenRef;
-    ShortName?: TokenRef;
-    Description?: TokenRef;
-    Attributes: Record<string, AttributeDefinitionDocument>;
-    Operations?: Record<string, unknown>;
-    Rules?: Record<string, unknown>;
-}
-interface MetamodelDocument {
-    HREF?: string;
-    Version: string;
-    AssetTypes: Record<string, AssetTypeDocument>;
-}
-declare function toAttributeDefinition(doc: AttributeDefinitionDocument): AttributeDefinition;
-declare function toAssetType(doc: AssetTypeDocument): AssetType;
-declare function toMetamodel(doc: MetamodelDocument): Metamodel;
-/** Is this a metamodel document as meta.v1 delivers it? (A downloaded metamodel.json, say.) */
-declare function isMetamodelDocument(value: unknown): value is MetamodelDocument;
-declare function getMetamodel(transport: Transport): Promise<Metamodel>;
-declare function getAssetType(transport: Transport, token: AssetTypeToken): Promise<AssetType>;
-declare function getAttributeDefinition(transport: Transport, tokenref: AttributeTokenRef): Promise<AttributeDefinition>;
-
-type meta_AssetTypeDocument = AssetTypeDocument;
-type meta_AttributeDefinitionDocument = AttributeDefinitionDocument;
-type meta_MetamodelDocument = MetamodelDocument;
-type meta_NameRef = NameRef;
-type meta_TokenRef = TokenRef;
-declare const meta_getAssetType: typeof getAssetType;
-declare const meta_getAttributeDefinition: typeof getAttributeDefinition;
-declare const meta_getMetamodel: typeof getMetamodel;
-declare const meta_isMetamodelDocument: typeof isMetamodelDocument;
-declare const meta_toAssetType: typeof toAssetType;
-declare const meta_toAttributeDefinition: typeof toAttributeDefinition;
-declare const meta_toMetamodel: typeof toMetamodel;
-declare namespace meta {
-  export { meta_getAssetType as getAssetType, meta_getAttributeDefinition as getAttributeDefinition, meta_getMetamodel as getMetamodel, meta_isMetamodelDocument as isMetamodelDocument, meta_toAssetType as toAssetType, meta_toAttributeDefinition as toAttributeDefinition, meta_toMetamodel as toMetamodel };
-  export type { meta_AssetTypeDocument as AssetTypeDocument, meta_AttributeDefinitionDocument as AttributeDefinitionDocument, meta_MetamodelDocument as MetamodelDocument, meta_NameRef as NameRef, meta_TokenRef as TokenRef };
+/** What query.v1 said about each refused query: its exception type and message. */
+interface QueryRejection {
+    type: string | null;
+    message: string;
 }
-
 /**
  * Several queries in one request; one array of rows per query, in order, []
  * where a query matched nothing. A page is required on every query. A
@@ -5360,14 +5541,27 @@ declare function queries<Row extends Asset = Asset>(transport: Transport, qs: Qu
 /** One query, its rows. */
 declare function query<Row extends Asset = Asset>(transport: Transport, q: QueryBody, options?: ReadOptions): Promise<Row[]>;
 
+type queryV1_QueryRejection = QueryRejection;
 declare const queryV1_queries: typeof queries;
 declare const queryV1_query: typeof query;
 declare namespace queryV1 {
+  export { queryV1_queries as queries, queryV1_query as query };
+  export type { queryV1_QueryRejection as QueryRejection };
+}
+
+/** The attributes shown for each type in the scopes given: a map from type token to sorted attribute names. */
+declare function visibleFields(transport: Transport, types: readonly AssetTypeToken[], scopes: readonly Oid[]): Promise<Record<AssetTypeToken, string[]>>;
+/** The attributes shown for one asset, in its own Scope. */
+declare function visibleFieldsByAsset(transport: Transport, oid: Oid): Promise<string[]>;
+
+declare const fields_visibleFields: typeof visibleFields;
+declare const fields_visibleFieldsByAsset: typeof visibleFieldsByAsset;
+declare namespace fields {
   export {
-    queryV1_queries as queries,
-    queryV1_query as query,
+    fields_visibleFields as visibleFields,
+    fields_visibleFieldsByAsset as visibleFieldsByAsset,
   };
 }
 
-export { ASSET_STATE_CODES, AgilityApiClient, ApiError, AttachmentUploadError, BatchRecordError, BatchSendError, CommandFailureError, INLINE_LIMIT, INVERSE, NUMBER_ROOTS, CHUNK as RESOLVE_CHUNK, Schema, TypeCache, UNGUARDABLE_TYPES, UnguardableError, UsageError, WrappedError, assetApi, assetStateOf, attachment, createFetchTransport, describe as describeBatch, guard, isAssetNumber, isOidToken, kindOf, loc2, meta, momentless, namesOf, parseOid, parseViolation, queryV1, resolveNumbers, resolveRef, rest1, reverseOf, reversible, runBatch, select, sendGuarded, snapshot, stampsOf, toOid, touchedBy, typeOfOid, unguardable };
-export type { Access, Actual, Allocation, Application, Asset, AssetApiResponse, AssetChangedEventDefinition, AssetCreatedEventDefinition, AssetDocument, AssetNumberAttributeDefinition, AssetStateValue, AssetType, AssetTypeMap, AssetTypeName, AssetTypeToken, AssetsDocument, Attachment, AddOptions as AttachmentAddOptions, AttachmentCategory, AttachmentInfo, AttributeAddedEventDefinition, AttributeChangedEventDefinition, AttributeDefinition, AttributeLookup, AttributeRemovedEventDefinition, AttributeTokenRef, AttributeType, AttributeValue, BaseAsset, BatchOptions, Budget, BuildProject, BuildRun, BuildSource, BuildStatus, Bundle, BusinessRule, Bytes, CalendarEvent, CalendarEventCategory, Capacity, ChangeSet, ClassOfService, ClientConfig, ClientOptions, Command, CommandBody, CommandFailureDetail, CommandValue, Community, Concept, ConcreteAssetTypeName, Conversation, CreateBody, CreateType, CredentialsAttributeDefinition, CustomAttributes, CustomList, DateString, DefaultRule, Defect, DefectResolution, DefectType, Delivery, DeliveryCategory, Described, EmbeddedImage$1 as EmbeddedImage, Environment, Epic, EpicCategory, EpicPriority, EpicStatus, ErrorKind, ExecuteBody, ExecuteSecurityCheckAttributeDefinition, Expression, ExpressionImage, ExpressionSpace, ExternalAction, ExternalActionInvocation, FetchTransportConfig, From, Goal, GoalCategory, GoalPriority, Grant, GuardedResult, HierarchyRelationDefinition, Idea, IdeaCategory, IdeaChangeSet, IdeaComment, IdeaForum, IdeaStatus, IdeaUser, IdeasUserCache, Image, Issue, IssueCategory, IssuePriority, IssueResolution, IssueStatus, KeyResult, KeyResultCommitment, KeyResultUnit, Label, Link, LinkCategory, List, Localizations, LocalizeOptions, ManyToManyRelationDefinition, Me, Member, MemberLabel, Message, MessageReceipt, Metamodel, Milestone, MilestoneCategory, MultivalueAttributeDefinition, NameLookupFailure, Named, NoteCategory, Oid, OidParts, Okr, OkrObjective, OkrSession, OneToManyRelationDefinition, OperationExecutedEventDefinition, Outcome, Page, PagesOptions, PasswordAttributeDefinition, Phase, PlanningLevel, PlanningRoom, PrimaryWorkitem, PrincipalAttributeDefinition, Publication, QueryBody, ReadOptions, ReadParams, ReadResult, Receipt, Ref, RegressionPlan, RegressionSuite, RegressionTest, RegressionTestStatus, Release, Request, RequestBody, RequestCategory, RequestOptions, RequestPriority, RequestResolution, RequestStatus, Resolution, ResolvedAsset, ResponseType, Retrospective, RetrospectivePrompt, RetrospectiveTopic, Reverse, Roadmap, Role, Room, RowContext, RowOf, RowsOf, SavedView, Schedule, Scheme, Scope, ScopeLabel, ScopeStatus, SelectKey, SelectPath, SelectValue, Selected, SendOptions, SimpleAttributeDefinition, State, Status, Story, StoryCategory, StorySource, StoryStatus, StrategicTheme, StrategicThemeLevel, Subscription, SubscriptionTerm, SyntheticAttributeDefinition, Task, TaskCategory, TaskSource, TaskStatus, Team, TeamRoom, TeamWorkflow, Test, TestCategory, TestRun, TestSet, TestStatus, TestSuite, Theme, ThemeCategory, ThemeLabel, ThemeSource, ThemeStatus, Timebox, Timesheet, Topic, Transport, TriggerType, TypeOf, UnauthorizedContext, UnauthorizedDecision, Unguardable, UpdateBody, UpdateSecurityCheckAttributeDefinition, ValueStream, VersionLabel, Violation, Workflow, WorkflowTransition, Workitem, WorkitemPriority, WorkitemRisk };
+export { ASSET_STATE_CODES, AgilityApiClient, ApiError, AttachmentUploadError, BatchRecordError, BatchSendError, CommandFailureError, INLINE_LIMIT, INVERSE, NUMBER_ROOTS, CHUNK as RESOLVE_CHUNK, Schema, TypeCache, UNGUARDABLE_TYPES, UnguardableError, UsageError, WrappedError, assetApi, assetStateOf, attachment, createFetchTransport, describe as describeBatch, fields, guard, importantName, isAssetNumber, isOidToken, kindOf, loc2, meta, momentless, namesOf, parseOid, parseViolation, queryV1, resolveNumbers, resolveRef, rest1, reverseOf, reversible, runBatch, select, sendGuarded, snapshot, stampsOf, toOid, touchedBy, typeOfOid, unguardable };
+export type { Access, Actual, Allocation, Application, Asset, AssetApiResponse, AssetChangedEventDefinition, AssetCreatedEventDefinition, AssetDocument, AssetNumberAttributeDefinition, AssetStateValue, AssetType, AssetTypeMap, AssetTypeName, AssetTypeToken, AssetsDocument, Attachment, AddOptions as AttachmentAddOptions, AttachmentCategory, AttachmentInfo, AttributeAddedEventDefinition, AttributeChangedEventDefinition, AttributeDefinition, AttributeLookup, AttributeRemovedEventDefinition, AttributeTokenRef, AttributeType, AttributeValue, BaseAsset, BatchOptions, Budget, BuildProject, BuildRun, BuildSource, BuildStatus, Bundle, BusinessRule, Bytes, CalendarEvent, CalendarEventCategory, Capacity, ChangeSet, ClassOfService, ClientConfig, ClientOptions, Command, CommandBody, CommandFailureDetail, CommandValue, Community, Concept, ConcreteAssetTypeName, ConditionalOptions, Conversation, CreateBody, CreateType, CredentialsAttributeDefinition, CustomAttributes, CustomList, DateString, DefaultRule, Defect, DefectResolution, DefectType, Delivery, DeliveryCategory, Described, EmbeddedImage$1 as EmbeddedImage, Environment, Epic, EpicCategory, EpicPriority, EpicStatus, ErrorKind, ExecuteBody, ExecuteSecurityCheckAttributeDefinition, Expression, ExpressionImage, ExpressionSpace, ExternalAction, ExternalActionInvocation, FetchTransportConfig, FieldsOf, From, Goal, GoalCategory, GoalPriority, Grant, GuardedResult, HierarchyRelationDefinition, Idea, IdeaCategory, IdeaChangeSet, IdeaComment, IdeaForum, IdeaStatus, IdeaUser, IdeasUserCache, Image, Issue, IssueCategory, IssuePriority, IssueResolution, IssueStatus, KeyResult, KeyResultCommitment, KeyResultUnit, Label, Link, LinkCategory, List, Localizations, LocalizeOptions, ManyToManyRelationDefinition, Me, Member, MemberLabel, Message, MessageReceipt, Metamodel, Milestone, MilestoneCategory, MultivalueAttributeDefinition, NameLookupFailure, Named, NoteCategory, Oid, OidParts, Okr, OkrObjective, OkrSession, OneToManyRelationDefinition, OperationExecutedEventDefinition, OperationResult, Outcome, Page, PagesOptions, PasswordAttributeDefinition, Phase, PlanningLevel, PlanningRoom, PrimaryWorkitem, PrincipalAttributeDefinition, Publication, QueryBody, QueryRejection, ReadOptions, ReadParams, ReadResult, Receipt, Ref, RegressionPlan, RegressionSuite, RegressionTest, RegressionTestStatus, Release, Request, RequestBody, RequestCategory, RequestOptions, RequestPriority, RequestResolution, RequestStatus, Resolution, ResolvedAsset, ResponseType, Retrospective, RetrospectivePrompt, RetrospectiveTopic, Reverse, Roadmap, Role, Room, RowContext, RowOf, RowsOf, SavedView, Schedule, Scheme, Scope, ScopeLabel, ScopeStatus, SelectKey, SelectPath, SelectValue, Selected, SendOptions, SimpleAttributeDefinition, State, Status, Story, StoryCategory, StorySource, StoryStatus, StrategicTheme, StrategicThemeLevel, Subscription, SubscriptionTerm, SyntheticAttributeDefinition, Tagged, Task, TaskCategory, TaskSource, TaskStatus, Team, TeamRoom, TeamWorkflow, Template, Test, TestCategory, TestRun, TestSet, TestStatus, TestSuite, Theme, ThemeCategory, ThemeLabel, ThemeSource, ThemeStatus, Timebox, Timesheet, Topic, Transport, TriggerType, TypeOf, UnauthorizedContext, UnauthorizedDecision, Unguardable, UpdateBody, UpdateSecurityCheckAttributeDefinition, ValueStream, VersionLabel, Violation, Workflow, WorkflowTransition, Workitem, WorkitemPriority, WorkitemRisk };