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

package/dist/index.d.ts

@@ -75,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;
@@ -83,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>;
@@ -99,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;
@@ -115,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;
     /**
@@ -4287,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;
 }
@@ -4544,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;
 }
@@ -4576,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,
@@ -4980,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;
@@ -5213,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
@@ -5379,84 +5526,11 @@ declare class AgilityApiClient {
     };
 }
 
-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
@@ -5467,13 +5541,12 @@ 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 { 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. */
@@ -5491,4 +5564,4 @@ declare namespace fields {
 }
 
 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, 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, 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, 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 };
+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 };

package/dist/index.js

@@ -117,10 +117,22 @@ function messageOf(data, status) {
   return `HTTP ${status}`;
 }
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var MAX_RETRY_AFTER_MS = 3e4;
+function retryDelay(response, attempt) {
+  const header = response.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(header) - Date.now();
+    if (Number.isFinite(ms) && ms > MAX_RETRY_AFTER_MS) return null;
+    if (Number.isFinite(ms) && ms > 0) return ms;
+  }
+  return 150 * (attempt + 1);
+}
+var retriable = (status) => status === 429 || status >= 500;
 function createFetchTransport(config) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const timeoutMs = config.timeoutMs ?? 6e4;
-  const retries = Math.max(0, config.retries ?? 0);
+  const retries = Math.max(0, config.retries ?? 1);
   const authorization = config.authorization ?? (config.accessToken ? `Bearer ${config.accessToken}` : void 0);
   const unauthorizedStatuses = config.unauthorizedStatuses ?? [401];
   return {
@@ -163,6 +175,10 @@ function createFetchTransport(config) {
             options.onResponse?.({ status: response.status, headers: response.headers });
             return await readBody(response, responseType);
           }
+          if (response.status === 304 && options.acceptNotModified) {
+            options.onResponse?.({ status: 304, headers: response.headers });
+            return void 0;
+          }
           const data = await readBody(response, responseType === "bytes" ? "text" : responseType === "json" ? "auto" : responseType);
           lastError = new ApiError(messageOf(data, response.status), response.status, void 0, data);
         } catch (error) {
@@ -181,8 +197,10 @@ function createFetchTransport(config) {
           }
           break;
         }
-        if (response.status >= 500 && attempt + 1 < attempts) {
-          await delay(150 * (attempt + 1));
+        if (retriable(response.status) && attempt + 1 < attempts) {
+          const wait = retryDelay(response, attempt);
+          if (wait === null) break;
+          await delay(wait);
           continue;
         }
         break;
@@ -389,6 +407,11 @@ function toNumber(value) {
   const n = typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
   return Number.isNaN(n) ? value : n;
 }
+function failureDetail(index, message, echoed) {
+  const detail = { index, message, violation: parseViolation(message) };
+  Object.defineProperty(detail, "echoed", { value: echoed, enumerable: false, writable: false });
+  return detail;
+}
 function parseViolation(message) {
   const parts = message.trim().split("'");
   if (parts[0] !== "Violation" || !parts[1]) return null;
@@ -398,12 +421,11 @@ function parseViolation(message) {
   return { rule, attribute: token, tag: !token && rest.length > 1 ? rest.join("'") : null };
 }
 function failuresOf(response) {
-  return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => ({
-    index: typeof error === "object" && error && typeof error.sourceCommandIndex === "number" ? error.sourceCommandIndex : null,
-    message: typeof error === "string" ? error : error?.message || "command failed",
-    echoed,
-    violation: parseViolation(typeof error === "string" ? error : error?.message || "")
-  }));
+  return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => failureDetail(
+    typeof error === "object" && error && typeof error.sourceCommandIndex === "number" ? error.sourceCommandIndex : null,
+    typeof error === "string" ? error : error?.message || "command failed",
+    echoed
+  ));
 }
 function outcomeOf(response) {
   return {
@@ -421,7 +443,7 @@ 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.failures.push(...done.failures.map((f) => failureDetail(f.index === null ? null : f.index + offset, f.message, f.echoed)));
   into.queryResults.push(...done.queryResults);
   into.requestId = null;
   if (done.durationSeconds !== null) into.durationSeconds = (into.durationSeconds ?? 0) + done.durationSeconds;
@@ -1255,10 +1277,13 @@ async function resolveRef(transport, spec, options = {}) {
 // src/wire/meta.ts
 var meta_exports = {};
 __export(meta_exports, {
+  etag: () => etag,
   getAssetType: () => getAssetType,
   getAttributeDefinition: () => getAttributeDefinition,
   getMetamodel: () => getMetamodel,
   isMetamodelDocument: () => isMetamodelDocument,
+  readAssetType: () => readAssetType,
+  readMetamodel: () => readMetamodel,
   toAssetType: () => toAssetType,
   toAttributeDefinition: () => toAttributeDefinition,
   toMetamodel: () => toMetamodel
@@ -1303,12 +1328,36 @@ function toMetamodel(doc) {
 function isMetamodelDocument(value) {
   return !!value && typeof value === "object" && typeof value.Version === "string" && !!value.AssetTypes && typeof value.AssetTypes === "object";
 }
+var PROBE_PATH = "/meta.v1/BaseAsset/Name";
+async function conditional(transport, path, options) {
+  let etag2 = null, status = 200;
+  const onResponse = (r) => {
+    status = r.status;
+    etag2 = r.headers.get("etag");
+  };
+  const headers = options.ifNoneMatch ? { "if-none-match": options.ifNoneMatch } : void 0;
+  const doc = await transport.request({ method: "GET", path, headers, responseType: "json", onResponse, acceptNotModified: !!options.ifNoneMatch });
+  if (status === 304 || doc === void 0) return null;
+  return { value: doc, etag: etag2 };
+}
 async function getMetamodel(transport) {
   return toMetamodel(await transport.request({ method: "GET", path: "/meta.v1", responseType: "json" }));
 }
+async function readMetamodel(transport, options = {}) {
+  const read2 = await conditional(transport, "/meta.v1", options);
+  return read2 && { value: toMetamodel(read2.value), etag: read2.etag };
+}
 async function getAssetType(transport, token) {
   return toAssetType(await transport.request({ method: "GET", path: `/meta.v1/${encodeURIComponent(token)}`, responseType: "json" }));
 }
+async function readAssetType(transport, token, options = {}) {
+  const read2 = await conditional(transport, `/meta.v1/${encodeURIComponent(token)}`, options);
+  return read2 && { value: toAssetType(read2.value), etag: read2.etag };
+}
+async function etag(transport, options = {}) {
+  const read2 = await conditional(transport, PROBE_PATH, options);
+  return read2 ? read2.etag : options.ifNoneMatch ?? null;
+}
 async function getAttributeDefinition(transport, tokenref) {
   const [type, attribute] = tokenref.split(".");
   if (!type || !attribute) throw new UsageError(`"${tokenref}" is not an attribute token ("Story.Name")`);
@@ -1320,6 +1369,13 @@ var TypeCache = class _TypeCache {
   /** Loaded types; null records that the instance has no such type, so it is not asked for again. */
   types = /* @__PURE__ */ new Map();
   loading = /* @__PURE__ */ new Map();
+  /** 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 = null;
+  /** Forget every loaded type (and the tag): the next query loads afresh. In-flight loads finish into the cache as before. */
+  clear() {
+    this.types.clear();
+    this.etag = null;
+  }
   /** A cache seeded from a metamodel document. */
   static fromMetamodel(metamodel) {
     const cache = new _TypeCache();
@@ -1384,7 +1440,10 @@ var Schema = class _Schema {
       this.types.set(token, null);
       return null;
     }
-    const request = getAssetType(this.transport, token).catch((error) => {
+    const request = readAssetType(this.transport, token).then((read2) => {
+      if (read2?.etag) this.cache.etag = read2.etag;
+      return read2 ? read2.value : null;
+    }).catch((error) => {
       if (error instanceof ApiError && error.status === 404) return null;
       throw error;
     }).then((type) => {
@@ -1394,6 +1453,23 @@ var Schema = class _Schema {
     this.loading.set(token, request);
     return request;
   }
+  /**
+   * 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.
+   */
+  async revalidate() {
+    if (!this.transport) return { changed: false, etag: this.cache.etag };
+    const was = this.cache.etag;
+    const now2 = await etag(this.transport, { ifNoneMatch: was });
+    if (was && now2 === was) return { changed: false, etag: was };
+    this.cache.clear();
+    this.cache.etag = now2;
+    return { changed: true, etag: now2 };
+  }
   /**
    * 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,
@@ -1454,8 +1530,8 @@ __export(queryV1_exports, {
 });
 function rejected(error) {
   const details = error.details;
-  const messages = (details?.exceptions ?? []).map((e) => e?.message).filter((m) => typeof m === "string" && !!m);
-  return messages.length ? new ApiError(messages.join("; "), error.status, "QUERY_REJECTED", error.details) : error;
+  const rejections = (details?.exceptions ?? []).filter((e) => e && typeof e.message === "string" && e.message).map((e) => ({ type: typeof e.type === "string" ? e.type : null, message: e.message }));
+  return rejections.length ? new ApiError(rejections.map((r) => r.message).join("; "), error.status, "QUERY_REJECTED", rejections) : error;
 }
 async function queries2(transport, qs, options = {}) {
   for (const q of qs) if (!q.page) throw new UsageError(`query of ${q.from} without a page: every query.v1 read must be bounded`);
@@ -1639,11 +1715,21 @@ var AgilityApiClient = class _AgilityApiClient {
     return row;
   }
   // ---- the endpoints behind the reads -----------------------------------------------
-  /** 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.
+   */
   meta = {
     metamodel: () => getMetamodel(this.transport),
+    read: (options) => readMetamodel(this.transport, options),
     assetType: (token) => getAssetType(this.transport, token),
-    attributeDefinition: (tokenref) => getAttributeDefinition(this.transport, tokenref)
+    readType: (token, options) => readAssetType(this.transport, token, options),
+    attributeDefinition: (tokenref) => getAttributeDefinition(this.transport, tokenref),
+    etag: (options) => etag(this.transport, options)
   };
   /**
    * loc-2.v1: labels for tags, in one request (meta's DisplayName values are