@covia/covia-sdk 1.7.2 → 1.7.3

package/README.md

@@ -577,12 +577,14 @@ The SDK provides a hierarchy of typed errors:
 
 ```typescript
 import {
+  Venue,
   CoviaError,          // Base error
   GridError,           // HTTP API errors (4xx/5xx)
   NotFoundError,       // 404 responses
   AssetNotFoundError,  // Asset not found
   JobNotFoundError,    // Job not found
-  CoviaConnectionError,// Connection failures
+  CoviaConnectionError,// Transport/connect failures (url, method, attempts)
+  VenueIdentityChangedError, // Same address now reports a different DID
   CoviaTimeoutError,   // Timeout exceeded
   JobFailedError,      // Job finished with non-COMPLETE status
   RateLimitError,      // 429 after bounded retries (carries retryAfterSeconds)
@@ -609,6 +611,32 @@ try {
 }
 ```
 
+Transport failures include the exact request target and method. A failed
+`Venue.connect()` additionally includes every candidate and failed validation
+request:
+
+```typescript
+try {
+  await Venue.connect("localhost:8080");
+} catch (err) {
+  if (err instanceof CoviaConnectionError) {
+    console.error(err.candidates);
+    for (const attempt of err.attempts) {
+      console.error(attempt.method, attempt.url, attempt.error.message);
+    }
+  }
+}
+
+try {
+  await venue.status();
+} catch (err) {
+  if (err instanceof VenueIdentityChangedError) {
+    console.error(`Venue changed from ${err.oldDid} to ${err.newDid}`);
+    // Reconnect and re-authorise explicitly; the old handle is not rebound.
+  }
+}
+```
+
 ## Job Status
 
 ```typescript

package/dist/index.d.mts

@@ -715,6 +715,8 @@ declare class Venue implements VenueInterface {
      *   responded (the https candidate if an http fallback failed; the resolved
      *   endpoint for a did:web id), and `venue.venueId` is the DID the venue
      *   reported. The validated API root is `${venue.baseUrl}/api/v1`.
+     * @throws {CoviaConnectionError} If no candidate can be validated.
+     * @throws {VenueIdentityChangedError} If a known/resolved DID reports a different identity.
      */
     static connect(venueId: string | Venue, auth?: Auth): Promise<Venue>;
     /**
@@ -760,6 +762,7 @@ declare class Venue implements VenueInterface {
     /**
      * Get venue status
      * @returns {Promise<StatusData>}
+     * @throws {VenueIdentityChangedError} If this address reports a different known DID.
      */
     status(): Promise<StatusData>;
     /**
@@ -774,6 +777,7 @@ declare class Venue implements VenueInterface {
      * @param options.pollIntervalMs - Delay between polls (default 1000).
      * @returns The ready {@link StatusData}.
      * @throws {CoviaTimeoutError} If the venue is not ready within the timeout.
+     * @throws {VenueIdentityChangedError} Immediately if the venue's DID changed.
      */
     waitUntilReady(options?: {
         timeoutMs?: number;
@@ -1323,9 +1327,47 @@ declare class GridError extends CoviaError {
     responseBody: unknown;
     constructor(statusCode: number, message: string, responseBody?: unknown);
 }
-/** Raised when the SDK cannot connect to the venue. */
+/** One failed HTTP request made while resolving/validating a venue connection. */
+interface ConnectionAttempt {
+    readonly url: string;
+    readonly method: string;
+    readonly error: CoviaError;
+}
+interface CoviaConnectionErrorOptions {
+    /** Exact request target for a single transport failure. */
+    url?: string;
+    /** HTTP method for a single transport failure. */
+    method?: string;
+    /** Original exception, or the final failed attempt for an aggregate error. */
+    cause?: unknown;
+    /** Ordered venue base URLs considered by `Venue.connect()`. */
+    candidates?: readonly string[];
+    /** Ordered failed requests made while validating those candidates. */
+    attempts?: readonly ConnectionAttempt[];
+}
+/**
+ * Raised when an HTTP request cannot be made, or when `Venue.connect()` cannot
+ * validate any candidate. HTTP responses still use `GridError`; this class is
+ * for transport failures and connection-attempt aggregation.
+ */
 declare class CoviaConnectionError extends CoviaError {
-    constructor(message: string);
+    readonly url: string | null;
+    readonly method: string | null;
+    readonly cause: unknown;
+    readonly candidates: readonly string[];
+    readonly attempts: readonly ConnectionAttempt[];
+    constructor(message: string, options?: CoviaConnectionErrorOptions);
+}
+/**
+ * Raised when a known venue address reports a different DID. The instance
+ * remains bound to `oldDid`; callers must explicitly reconnect/re-authorise
+ * against `newDid` rather than silently continuing under a new identity.
+ */
+declare class VenueIdentityChangedError extends CoviaError {
+    readonly oldDid: string;
+    readonly newDid: string;
+    readonly baseUrl: string;
+    constructor(oldDid: string, newDid: string, baseUrl: string);
 }
 /** Raised when an operation or polling loop times out. */
 declare class CoviaTimeoutError extends CoviaError {
@@ -1638,4 +1680,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, Auth, BasicAuth, BearerAuth, ChatSession, type ContentDetails, type ContentHashResult, CoviaConnectionError, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, DataAsset, Ed25519Auth, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, Auth, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, DataAsset, Ed25519Auth, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.d.ts

@@ -715,6 +715,8 @@ declare class Venue implements VenueInterface {
      *   responded (the https candidate if an http fallback failed; the resolved
      *   endpoint for a did:web id), and `venue.venueId` is the DID the venue
      *   reported. The validated API root is `${venue.baseUrl}/api/v1`.
+     * @throws {CoviaConnectionError} If no candidate can be validated.
+     * @throws {VenueIdentityChangedError} If a known/resolved DID reports a different identity.
      */
     static connect(venueId: string | Venue, auth?: Auth): Promise<Venue>;
     /**
@@ -760,6 +762,7 @@ declare class Venue implements VenueInterface {
     /**
      * Get venue status
      * @returns {Promise<StatusData>}
+     * @throws {VenueIdentityChangedError} If this address reports a different known DID.
      */
     status(): Promise<StatusData>;
     /**
@@ -774,6 +777,7 @@ declare class Venue implements VenueInterface {
      * @param options.pollIntervalMs - Delay between polls (default 1000).
      * @returns The ready {@link StatusData}.
      * @throws {CoviaTimeoutError} If the venue is not ready within the timeout.
+     * @throws {VenueIdentityChangedError} Immediately if the venue's DID changed.
      */
     waitUntilReady(options?: {
         timeoutMs?: number;
@@ -1323,9 +1327,47 @@ declare class GridError extends CoviaError {
     responseBody: unknown;
     constructor(statusCode: number, message: string, responseBody?: unknown);
 }
-/** Raised when the SDK cannot connect to the venue. */
+/** One failed HTTP request made while resolving/validating a venue connection. */
+interface ConnectionAttempt {
+    readonly url: string;
+    readonly method: string;
+    readonly error: CoviaError;
+}
+interface CoviaConnectionErrorOptions {
+    /** Exact request target for a single transport failure. */
+    url?: string;
+    /** HTTP method for a single transport failure. */
+    method?: string;
+    /** Original exception, or the final failed attempt for an aggregate error. */
+    cause?: unknown;
+    /** Ordered venue base URLs considered by `Venue.connect()`. */
+    candidates?: readonly string[];
+    /** Ordered failed requests made while validating those candidates. */
+    attempts?: readonly ConnectionAttempt[];
+}
+/**
+ * Raised when an HTTP request cannot be made, or when `Venue.connect()` cannot
+ * validate any candidate. HTTP responses still use `GridError`; this class is
+ * for transport failures and connection-attempt aggregation.
+ */
 declare class CoviaConnectionError extends CoviaError {
-    constructor(message: string);
+    readonly url: string | null;
+    readonly method: string | null;
+    readonly cause: unknown;
+    readonly candidates: readonly string[];
+    readonly attempts: readonly ConnectionAttempt[];
+    constructor(message: string, options?: CoviaConnectionErrorOptions);
+}
+/**
+ * Raised when a known venue address reports a different DID. The instance
+ * remains bound to `oldDid`; callers must explicitly reconnect/re-authorise
+ * against `newDid` rather than silently continuing under a new identity.
+ */
+declare class VenueIdentityChangedError extends CoviaError {
+    readonly oldDid: string;
+    readonly newDid: string;
+    readonly baseUrl: string;
+    constructor(oldDid: string, newDid: string, baseUrl: string);
 }
 /** Raised when an operation or polling loop times out. */
 declare class CoviaTimeoutError extends CoviaError {
@@ -1638,4 +1680,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, Auth, BasicAuth, BearerAuth, ChatSession, type ContentDetails, type ContentHashResult, CoviaConnectionError, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, DataAsset, Ed25519Auth, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, Auth, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, DataAsset, Ed25519Auth, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.js

@@ -46,9 +46,23 @@ var GridError = class extends CoviaError {
   }
 };
 var CoviaConnectionError = class extends CoviaError {
-  constructor(message) {
+  constructor(message, options = {}) {
     super(message);
     this.name = "CoviaConnectionError";
+    this.url = options.url ?? null;
+    this.method = options.method?.toUpperCase() ?? null;
+    this.cause = options.cause;
+    this.candidates = [...options.candidates ?? []];
+    this.attempts = [...options.attempts ?? []];
+  }
+};
+var VenueIdentityChangedError = class extends CoviaError {
+  constructor(oldDid, newDid, baseUrl) {
+    super(`Venue identity changed at ${baseUrl}: expected ${oldDid}, received ${newDid}`);
+    this.oldDid = oldDid;
+    this.newDid = newDid;
+    this.baseUrl = baseUrl;
+    this.name = "VenueIdentityChangedError";
   }
 };
 var CoviaTimeoutError = class extends CoviaError {
@@ -1308,13 +1322,14 @@ async function throwHttpError(response) {
   }
   throw new GridError(response.status, message, body);
 }
-function wrapError(error) {
-  if (error instanceof CoviaError) return error;
-  const msg = error.message ?? String(error);
-  if (error instanceof TypeError) {
-    return new CoviaConnectionError(msg);
-  }
-  return new CoviaError(`Request failed: ${msg}`);
+function wrapConnectionError(error, url, method) {
+  if (error instanceof CoviaConnectionError && error.url && error.method) return error;
+  const detail = error instanceof Error ? error.message : String(error);
+  return new CoviaConnectionError(`${method} ${url} failed: ${detail}`, {
+    url,
+    method,
+    cause: error
+  });
 }
 var RETRY_MAX_ATTEMPTS = 4;
 var RETRY_BASE_MS = 200;
@@ -1335,7 +1350,7 @@ function retryDelayMs(attempt, retryAfterMs, remainingBudgetMs, random) {
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function fetchWithError(url, options) {
-  const method = options?.method ?? "GET";
+  const method = (options?.method ?? "GET").toUpperCase();
   const deadline = Date.now() + RETRY_BUDGET_MS;
   for (let attempt = 1; ; attempt++) {
     logger.debug(`${method} ${url}`);
@@ -1345,7 +1360,7 @@ async function fetchWithError(url, options) {
     } catch (error) {
       const msg = error.message ?? String(error);
       logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
-      throw wrapError(error);
+      throw wrapConnectionError(error, url, method);
     }
     logger.debug(`${method} ${url} \u2192 ${response.status}`);
     if (response.status === 429) {
@@ -1367,7 +1382,7 @@ async function fetchWithError(url, options) {
   }
 }
 async function fetchStreamWithError(url, options) {
-  const method = options?.method ?? "GET";
+  const method = (options?.method ?? "GET").toUpperCase();
   logger.debug(`${method} ${url}`);
   let response;
   try {
@@ -1375,7 +1390,7 @@ async function fetchStreamWithError(url, options) {
   } catch (error) {
     const msg = error.message ?? String(error);
     logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
-    throw wrapError(error);
+    throw wrapConnectionError(error, url, method);
   }
   logger.debug(`${method} ${url} \u2192 ${response.status}`);
   if (!response.ok) {
@@ -2070,7 +2085,9 @@ var AssetManager = class {
       }
     }
     try {
-      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`);
+      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
+        headers: this._buildHeaders(null)
+      });
       if (hash) {
         cache.set(assetId, data);
         getAssetMetadataStore()?.put(normaliseHash(hash), data);
@@ -2099,7 +2116,9 @@ var AssetManager = class {
     if (options.limit !== void 0) {
       params.set("limit", String(options.limit));
     }
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets?${params.toString()}`);
+    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets?${params.toString()}`, {
+      headers: this._buildHeaders(null)
+    });
   }
   /**
    * Register a new asset
@@ -2118,7 +2137,9 @@ var AssetManager = class {
    */
   async getMetadata(assetId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`);
+      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
+        headers: this._buildHeaders(null)
+      });
     } catch (error) {
       if (error instanceof NotFoundError) {
         throw new AssetNotFoundError(assetId);
@@ -2152,7 +2173,9 @@ var AssetManager = class {
    */
   async getContent(assetId) {
     try {
-      const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`);
+      const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`, {
+        headers: this._buildHeaders(null)
+      });
       return response.body;
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -2549,6 +2572,20 @@ function venueBaseUrlCandidates(venueId) {
   }
   return schemelessVenueCandidates(venueId);
 }
+function asCoviaError(error) {
+  if (error instanceof CoviaError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new CoviaError(message);
+}
+function assertVenueIdentity(expectedDid, actualDid, baseUrl) {
+  if (expectedDid && actualDid && expectedDid !== actualDid) {
+    throw new VenueIdentityChangedError(expectedDid, actualDid, baseUrl);
+  }
+}
+function connectionFailureMessage(venueId, attempts) {
+  const detail = attempts.map(({ method, url, error }) => `${method} ${url}: ${error.message}`).join("; ");
+  return `Could not connect to venue ${venueId}${detail ? `. Attempts: ${detail}` : ""}`;
+}
 var Venue = class _Venue {
   constructor(options = {}) {
     /** Connection-level private-jobs mode — see {@link setPrivate}. */
@@ -2619,20 +2656,26 @@ var Venue = class _Venue {
    *   responded (the https candidate if an http fallback failed; the resolved
    *   endpoint for a did:web id), and `venue.venueId` is the DID the venue
    *   reported. The validated API root is `${venue.baseUrl}/api/v1`.
+   * @throws {CoviaConnectionError} If no candidate can be validated.
+   * @throws {VenueIdentityChangedError} If a known/resolved DID reports a different identity.
    */
   static async connect(venueId, auth) {
     if (venueId instanceof _Venue) {
-      return new _Venue({
+      const connected = new _Venue({
         baseUrl: venueId.baseUrl,
         venueId: venueId.venueId,
         name: venueId.metadata.name,
         auth,
         status: venueId.lastKnownStatus
       });
+      await connected.status();
+      return connected;
     }
     if (typeof venueId === "string") {
       let candidates;
+      let expectedDid;
       if (venueId.startsWith("did:web:")) {
+        expectedDid = venueId;
         const didDoc = await resolver.resolve(venueId);
         if (!didDoc.didDocument) {
           throw new CoviaError("Invalid DID document");
@@ -2645,10 +2688,15 @@ var Venue = class _Venue {
       } else {
         candidates = venueBaseUrlCandidates(venueId);
       }
-      let lastError;
+      const attempts = [];
       for (const baseUrl of candidates) {
+        const statusUrl = baseUrl + "/api/v1/status";
         try {
-          const data = await fetchWithError(baseUrl + "/api/v1/status");
+          const data = await fetchWithError(statusUrl);
+          if (!data.did) {
+            throw new CoviaError(`Venue status at ${statusUrl} did not include a DID`);
+          }
+          assertVenueIdentity(expectedDid, data.did, baseUrl);
           return new _Venue({
             baseUrl,
             venueId: data.did,
@@ -2657,19 +2705,30 @@ var Venue = class _Venue {
             status: data
           });
         } catch (error) {
-          if (error instanceof GridError && (error.statusCode === 401 || error.statusCode === 403)) {
+          if (error instanceof VenueIdentityChangedError) throw error;
+          const statusError = asCoviaError(error);
+          attempts.push({ url: statusUrl, method: "GET", error: statusError });
+          if (statusError instanceof GridError && (statusError.statusCode === 401 || statusError.statusCode === 403)) {
+            const didDocumentUrl = baseUrl + "/.well-known/did.json";
             try {
-              const doc = await fetchWithError(baseUrl + "/.well-known/did.json");
+              const doc = await fetchWithError(didDocumentUrl);
               if (doc?.id) {
+                assertVenueIdentity(expectedDid, doc.id, baseUrl);
                 return new _Venue({ baseUrl, venueId: doc.id, auth });
               }
-            } catch {
+              throw new CoviaError(`DID document at ${didDocumentUrl} did not include an id`);
+            } catch (fallbackError) {
+              if (fallbackError instanceof VenueIdentityChangedError) throw fallbackError;
+              attempts.push({ url: didDocumentUrl, method: "GET", error: asCoviaError(fallbackError) });
             }
           }
-          lastError = error;
         }
       }
-      throw lastError instanceof Error ? lastError : new CoviaError(`Could not connect to venue: ${venueId}`);
+      throw new CoviaConnectionError(connectionFailureMessage(venueId, attempts), {
+        candidates,
+        attempts,
+        cause: attempts.length > 0 ? attempts[attempts.length - 1].error : void 0
+      });
     }
     throw new CoviaError("Invalid venue ID parameter. Must be a string (URL/DNS) or Venue instance.");
   }
@@ -2736,9 +2795,17 @@ var Venue = class _Venue {
   /**
    * Get venue status
    * @returns {Promise<StatusData>}
+   * @throws {VenueIdentityChangedError} If this address reports a different known DID.
    */
   async status() {
     const data = await fetchWithError(`${this.baseUrl}/api/v1/status`);
+    if (data.did) {
+      if (this.venueId) {
+        assertVenueIdentity(this.venueId, data.did, this.baseUrl);
+      } else {
+        this.venueId = data.did;
+      }
+    }
     this.lastKnownStatus = data;
     return data;
   }
@@ -2754,6 +2821,7 @@ var Venue = class _Venue {
    * @param options.pollIntervalMs - Delay between polls (default 1000).
    * @returns The ready {@link StatusData}.
    * @throws {CoviaTimeoutError} If the venue is not ready within the timeout.
+   * @throws {VenueIdentityChangedError} Immediately if the venue's DID changed.
    */
   async waitUntilReady(options = {}) {
     const timeoutMs = options.timeoutMs ?? 6e4;
@@ -2763,7 +2831,8 @@ var Venue = class _Venue {
       try {
         const data = await this.status();
         if (data.status == null || data.status.toUpperCase() === "OK") return data;
-      } catch {
+      } catch (error) {
+        if (error instanceof VenueIdentityChangedError) throw error;
       }
       if (Date.now() - start >= timeoutMs) {
         throw new CoviaTimeoutError(`Venue ${this.baseUrl} not ready within ${timeoutMs}ms`);
@@ -2904,6 +2973,7 @@ exports.SecretManager = SecretManager;
 exports.UCANManager = UCANManager;
 exports.VENUE_RELAY = VENUE_RELAY;
 exports.Venue = Venue;
+exports.VenueIdentityChangedError = VenueIdentityChangedError;
 exports.WorkspaceManager = WorkspaceManager;
 exports.assetHash = assetHash;
 exports.createSSEEvent = createSSEEvent;

package/dist/index.mjs

@@ -44,9 +44,23 @@ var GridError = class extends CoviaError {
   }
 };
 var CoviaConnectionError = class extends CoviaError {
-  constructor(message) {
+  constructor(message, options = {}) {
     super(message);
     this.name = "CoviaConnectionError";
+    this.url = options.url ?? null;
+    this.method = options.method?.toUpperCase() ?? null;
+    this.cause = options.cause;
+    this.candidates = [...options.candidates ?? []];
+    this.attempts = [...options.attempts ?? []];
+  }
+};
+var VenueIdentityChangedError = class extends CoviaError {
+  constructor(oldDid, newDid, baseUrl) {
+    super(`Venue identity changed at ${baseUrl}: expected ${oldDid}, received ${newDid}`);
+    this.oldDid = oldDid;
+    this.newDid = newDid;
+    this.baseUrl = baseUrl;
+    this.name = "VenueIdentityChangedError";
   }
 };
 var CoviaTimeoutError = class extends CoviaError {
@@ -1306,13 +1320,14 @@ async function throwHttpError(response) {
   }
   throw new GridError(response.status, message, body);
 }
-function wrapError(error) {
-  if (error instanceof CoviaError) return error;
-  const msg = error.message ?? String(error);
-  if (error instanceof TypeError) {
-    return new CoviaConnectionError(msg);
-  }
-  return new CoviaError(`Request failed: ${msg}`);
+function wrapConnectionError(error, url, method) {
+  if (error instanceof CoviaConnectionError && error.url && error.method) return error;
+  const detail = error instanceof Error ? error.message : String(error);
+  return new CoviaConnectionError(`${method} ${url} failed: ${detail}`, {
+    url,
+    method,
+    cause: error
+  });
 }
 var RETRY_MAX_ATTEMPTS = 4;
 var RETRY_BASE_MS = 200;
@@ -1333,7 +1348,7 @@ function retryDelayMs(attempt, retryAfterMs, remainingBudgetMs, random) {
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function fetchWithError(url, options) {
-  const method = options?.method ?? "GET";
+  const method = (options?.method ?? "GET").toUpperCase();
   const deadline = Date.now() + RETRY_BUDGET_MS;
   for (let attempt = 1; ; attempt++) {
     logger.debug(`${method} ${url}`);
@@ -1343,7 +1358,7 @@ async function fetchWithError(url, options) {
     } catch (error) {
       const msg = error.message ?? String(error);
       logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
-      throw wrapError(error);
+      throw wrapConnectionError(error, url, method);
     }
     logger.debug(`${method} ${url} \u2192 ${response.status}`);
     if (response.status === 429) {
@@ -1365,7 +1380,7 @@ async function fetchWithError(url, options) {
   }
 }
 async function fetchStreamWithError(url, options) {
-  const method = options?.method ?? "GET";
+  const method = (options?.method ?? "GET").toUpperCase();
   logger.debug(`${method} ${url}`);
   let response;
   try {
@@ -1373,7 +1388,7 @@ async function fetchStreamWithError(url, options) {
   } catch (error) {
     const msg = error.message ?? String(error);
     logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
-    throw wrapError(error);
+    throw wrapConnectionError(error, url, method);
   }
   logger.debug(`${method} ${url} \u2192 ${response.status}`);
   if (!response.ok) {
@@ -2068,7 +2083,9 @@ var AssetManager = class {
       }
     }
     try {
-      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`);
+      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
+        headers: this._buildHeaders(null)
+      });
       if (hash) {
         cache.set(assetId, data);
         getAssetMetadataStore()?.put(normaliseHash(hash), data);
@@ -2097,7 +2114,9 @@ var AssetManager = class {
     if (options.limit !== void 0) {
       params.set("limit", String(options.limit));
     }
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets?${params.toString()}`);
+    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets?${params.toString()}`, {
+      headers: this._buildHeaders(null)
+    });
   }
   /**
    * Register a new asset
@@ -2116,7 +2135,9 @@ var AssetManager = class {
    */
   async getMetadata(assetId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`);
+      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
+        headers: this._buildHeaders(null)
+      });
     } catch (error) {
       if (error instanceof NotFoundError) {
         throw new AssetNotFoundError(assetId);
@@ -2150,7 +2171,9 @@ var AssetManager = class {
    */
   async getContent(assetId) {
     try {
-      const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`);
+      const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`, {
+        headers: this._buildHeaders(null)
+      });
       return response.body;
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -2547,6 +2570,20 @@ function venueBaseUrlCandidates(venueId) {
   }
   return schemelessVenueCandidates(venueId);
 }
+function asCoviaError(error) {
+  if (error instanceof CoviaError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new CoviaError(message);
+}
+function assertVenueIdentity(expectedDid, actualDid, baseUrl) {
+  if (expectedDid && actualDid && expectedDid !== actualDid) {
+    throw new VenueIdentityChangedError(expectedDid, actualDid, baseUrl);
+  }
+}
+function connectionFailureMessage(venueId, attempts) {
+  const detail = attempts.map(({ method, url, error }) => `${method} ${url}: ${error.message}`).join("; ");
+  return `Could not connect to venue ${venueId}${detail ? `. Attempts: ${detail}` : ""}`;
+}
 var Venue = class _Venue {
   constructor(options = {}) {
     /** Connection-level private-jobs mode — see {@link setPrivate}. */
@@ -2617,20 +2654,26 @@ var Venue = class _Venue {
    *   responded (the https candidate if an http fallback failed; the resolved
    *   endpoint for a did:web id), and `venue.venueId` is the DID the venue
    *   reported. The validated API root is `${venue.baseUrl}/api/v1`.
+   * @throws {CoviaConnectionError} If no candidate can be validated.
+   * @throws {VenueIdentityChangedError} If a known/resolved DID reports a different identity.
    */
   static async connect(venueId, auth) {
     if (venueId instanceof _Venue) {
-      return new _Venue({
+      const connected = new _Venue({
         baseUrl: venueId.baseUrl,
         venueId: venueId.venueId,
         name: venueId.metadata.name,
         auth,
         status: venueId.lastKnownStatus
       });
+      await connected.status();
+      return connected;
     }
     if (typeof venueId === "string") {
       let candidates;
+      let expectedDid;
       if (venueId.startsWith("did:web:")) {
+        expectedDid = venueId;
         const didDoc = await resolver.resolve(venueId);
         if (!didDoc.didDocument) {
           throw new CoviaError("Invalid DID document");
@@ -2643,10 +2686,15 @@ var Venue = class _Venue {
       } else {
         candidates = venueBaseUrlCandidates(venueId);
       }
-      let lastError;
+      const attempts = [];
       for (const baseUrl of candidates) {
+        const statusUrl = baseUrl + "/api/v1/status";
         try {
-          const data = await fetchWithError(baseUrl + "/api/v1/status");
+          const data = await fetchWithError(statusUrl);
+          if (!data.did) {
+            throw new CoviaError(`Venue status at ${statusUrl} did not include a DID`);
+          }
+          assertVenueIdentity(expectedDid, data.did, baseUrl);
           return new _Venue({
             baseUrl,
             venueId: data.did,
@@ -2655,19 +2703,30 @@ var Venue = class _Venue {
             status: data
           });
         } catch (error) {
-          if (error instanceof GridError && (error.statusCode === 401 || error.statusCode === 403)) {
+          if (error instanceof VenueIdentityChangedError) throw error;
+          const statusError = asCoviaError(error);
+          attempts.push({ url: statusUrl, method: "GET", error: statusError });
+          if (statusError instanceof GridError && (statusError.statusCode === 401 || statusError.statusCode === 403)) {
+            const didDocumentUrl = baseUrl + "/.well-known/did.json";
             try {
-              const doc = await fetchWithError(baseUrl + "/.well-known/did.json");
+              const doc = await fetchWithError(didDocumentUrl);
               if (doc?.id) {
+                assertVenueIdentity(expectedDid, doc.id, baseUrl);
                 return new _Venue({ baseUrl, venueId: doc.id, auth });
               }
-            } catch {
+              throw new CoviaError(`DID document at ${didDocumentUrl} did not include an id`);
+            } catch (fallbackError) {
+              if (fallbackError instanceof VenueIdentityChangedError) throw fallbackError;
+              attempts.push({ url: didDocumentUrl, method: "GET", error: asCoviaError(fallbackError) });
             }
           }
-          lastError = error;
         }
       }
-      throw lastError instanceof Error ? lastError : new CoviaError(`Could not connect to venue: ${venueId}`);
+      throw new CoviaConnectionError(connectionFailureMessage(venueId, attempts), {
+        candidates,
+        attempts,
+        cause: attempts.length > 0 ? attempts[attempts.length - 1].error : void 0
+      });
     }
     throw new CoviaError("Invalid venue ID parameter. Must be a string (URL/DNS) or Venue instance.");
   }
@@ -2734,9 +2793,17 @@ var Venue = class _Venue {
   /**
    * Get venue status
    * @returns {Promise<StatusData>}
+   * @throws {VenueIdentityChangedError} If this address reports a different known DID.
    */
   async status() {
     const data = await fetchWithError(`${this.baseUrl}/api/v1/status`);
+    if (data.did) {
+      if (this.venueId) {
+        assertVenueIdentity(this.venueId, data.did, this.baseUrl);
+      } else {
+        this.venueId = data.did;
+      }
+    }
     this.lastKnownStatus = data;
     return data;
   }
@@ -2752,6 +2819,7 @@ var Venue = class _Venue {
    * @param options.pollIntervalMs - Delay between polls (default 1000).
    * @returns The ready {@link StatusData}.
    * @throws {CoviaTimeoutError} If the venue is not ready within the timeout.
+   * @throws {VenueIdentityChangedError} Immediately if the venue's DID changed.
    */
   async waitUntilReady(options = {}) {
     const timeoutMs = options.timeoutMs ?? 6e4;
@@ -2761,7 +2829,8 @@ var Venue = class _Venue {
       try {
         const data = await this.status();
         if (data.status == null || data.status.toUpperCase() === "OK") return data;
-      } catch {
+      } catch (error) {
+        if (error instanceof VenueIdentityChangedError) throw error;
       }
       if (Date.now() - start >= timeoutMs) {
         throw new CoviaTimeoutError(`Venue ${this.baseUrl} not ready within ${timeoutMs}ms`);
@@ -2866,4 +2935,4 @@ function relayDelegation(privateKey, venueDID, lifetimeSeconds, caps = []) {
   (*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) *)
 */
 
-export { AdapterManager, Agent, AgentManager, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, SecretManager, UCANManager, VENUE_RELAY, Venue, WorkspaceManager, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { AdapterManager, Agent, AgentManager, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, SecretManager, UCANManager, VENUE_RELAY, Venue, VenueIdentityChangedError, WorkspaceManager, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covia/covia-sdk",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Typescript library for covia-ai",
   "packageManager": "pnpm@11.9.0",
   "main": "./dist/index.js",