@usearete/sdk 0.26.0 → 0.28.0

package/dist/index.cjs

@@ -4,6 +4,97 @@ var pako = require('pako');
 var buffer = require('buffer');
 
 const DEFAULT_MAX_ENTRIES_PER_VIEW = 10000;
+const API_PROBLEM_SCHEMA_VERSION = 1;
+const CLAIM_AGENT_MATERIALIZER_PATH = '/api/agents/me/claim-links';
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSafeUnsignedInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function parseUsageLimit(value) {
+    if (!isRecord$1(value)
+        || typeof value['unit'] !== 'string'
+        || !isSafeUnsignedInteger(value['used'])
+        || !isSafeUnsignedInteger(value['limit'])
+        || (value['resetsAt'] !== undefined
+            && value['resetsAt'] !== null
+            && typeof value['resetsAt'] !== 'string')) {
+        return undefined;
+    }
+    return {
+        unit: value['unit'],
+        used: value['used'],
+        limit: value['limit'],
+        ...(value['resetsAt'] !== undefined ? { resetsAt: value['resetsAt'] } : {}),
+    };
+}
+function parseRecoveryAction(value) {
+    if (!isRecord$1(value) || typeof value['type'] !== 'string') {
+        return undefined;
+    }
+    if ((value['label'] !== undefined && typeof value['label'] !== 'string')
+        || (value['method'] !== undefined && typeof value['method'] !== 'string')
+        || (value['path'] !== undefined && typeof value['path'] !== 'string')) {
+        return undefined;
+    }
+    return value;
+}
+function isClaimAgentRecoveryAction(action) {
+    return action?.type === 'claim_agent'
+        && action.method === 'POST'
+        && action.path === CLAIM_AGENT_MATERIALIZER_PATH;
+}
+function parseApiProblem(value) {
+    if (!isRecord$1(value) || typeof value['error'] !== 'string') {
+        return undefined;
+    }
+    if (value['schemaVersion'] !== undefined
+        && (!isSafeUnsignedInteger(value['schemaVersion']) || value['schemaVersion'] < 1)) {
+        return undefined;
+    }
+    if ((value['code'] !== undefined && typeof value['code'] !== 'string')
+        || (value['retryable'] !== undefined && typeof value['retryable'] !== 'boolean')
+        || (value['requestId'] !== undefined && typeof value['requestId'] !== 'string')
+        || (value['retryAfterSeconds'] !== undefined
+            && value['retryAfterSeconds'] !== null
+            && !isSafeUnsignedInteger(value['retryAfterSeconds']))) {
+        return undefined;
+    }
+    const usage = value['usage'] === undefined ? undefined : parseUsageLimit(value['usage']);
+    const action = value['action'] === undefined ? undefined : parseRecoveryAction(value['action']);
+    if ((value['usage'] !== undefined && !usage) || (value['action'] !== undefined && !action)) {
+        return undefined;
+    }
+    return {
+        ...value,
+        error: value['error'],
+        ...(usage ? { usage } : {}),
+        ...(action ? { action } : {}),
+    };
+}
+function isSafeClaimActionUrl(action, expectedOrigin) {
+    if (action.type !== 'claim_agent')
+        return false;
+    try {
+        const url = new URL(action.url);
+        const origin = new URL(expectedOrigin);
+        const loopback = url.hostname === 'localhost'
+            || url.hostname === '127.0.0.1'
+            || url.hostname === '[::1]';
+        const secure = url.protocol === 'https:' || (url.protocol === 'http:' && loopback);
+        return secure
+            && url.origin === origin.origin
+            && url.username === ''
+            && url.password === ''
+            && url.pathname === '/claim'
+            && url.search === ''
+            && url.hash.length > 1;
+    }
+    catch {
+        return false;
+    }
+}
 const DEFAULT_CONFIG = {
     autoReconnect: true,
     reconnectIntervals: [1000, 2000, 4000, 8000, 16000],
@@ -45,6 +136,17 @@ class AreteError extends Error {
         this.details = details;
         this.name = 'AreteError';
     }
+    apiProblem() {
+        if (!isRecord$1(this.details))
+            return undefined;
+        return parseApiProblem(this.details['apiProblem']);
+    }
+    recoveryAction() {
+        return this.apiProblem()?.action;
+    }
+    retryAfter() {
+        return this.apiProblem()?.retryAfterSeconds ?? undefined;
+    }
 }
 /**
  * Parse a kebab-case error code string (from X-Error-Code header) to AuthErrorCode.
@@ -109,6 +211,7 @@ const AUTH_ERROR_CODES_BY_WIRE = {
     'secret-key-required': 'SECRET_KEY_REQUIRED',
     'deployment-access-denied': 'DEPLOYMENT_ACCESS_DENIED',
     'quota-exceeded': 'QUOTA_EXCEEDED',
+    'agent-claim-required': 'AGENT_CLAIM_REQUIRED',
     'stack-version-retired': 'STACK_VERSION_RETIRED',
     'stack-version-unknown': 'STACK_VERSION_UNKNOWN',
 };
@@ -1187,9 +1290,11 @@ class ConnectionManager {
         if (!response.ok) {
             const rawError = await response.text();
             let parsedError;
+            let parsedValue;
             if (rawError) {
                 try {
-                    parsedError = JSON.parse(rawError);
+                    parsedValue = JSON.parse(rawError);
+                    parsedError = parsedValue;
                 }
                 catch {
                     parsedError = undefined;
@@ -1205,19 +1310,32 @@ class ConnectionManager {
             const errorMessage = typeof parsedError?.error === 'string' && parsedError.error.length > 0
                 ? parsedError.error
                 : rawError || response.statusText || 'Authentication request failed';
+            const retryAfterHeader = response.headers.get('Retry-After');
+            const retryAfterSeconds = retryAfterHeader && /^\d+$/.test(retryAfterHeader)
+                ? Number(retryAfterHeader)
+                : undefined;
+            const parsedProblem = parseApiProblem(parsedValue);
+            const apiProblem = parsedProblem
+                ? {
+                    ...parsedProblem,
+                    ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+                }
+                : undefined;
             if (isStackVersionRefusalCode(errorCode)) {
                 const refusal = parseStackVersionRefusal(parsedError);
                 throw new AreteError(describeStackVersionRefusal(`Token endpoint returned ${response.status}: ${errorMessage}`, refusal), errorCode, {
                     status: response.status,
                     wireErrorCode,
                     responseBody: rawError || null,
+                    apiProblem,
                     ...refusal,
                 });
             }
             throw new AreteError(`Token endpoint returned ${response.status}: ${errorMessage}`, errorCode, {
                 status: response.status,
                 wireErrorCode,
-                responseBody: rawError || null,
+                apiProblem,
+                retryAfterSeconds,
             });
         }
         const data = (await response.json());
@@ -1478,6 +1596,8 @@ class ConnectionManager {
             code: parseWireErrorCode(message.code),
             retryable: message.retryable ?? false,
             retryAfter: message.retryAfter ?? message.retry_after,
+            usage: message.usage,
+            action: message.action,
             suggestedAction: message.suggestedAction ?? message.suggested_action,
             docsUrl: message.docsUrl ?? message.docs_url,
             fatal: message.fatal,
@@ -1839,7 +1959,12 @@ class ConnectionManager {
      * with the `reconnecting` state and kept for the terminal error if the
      * attempts run out, so a server's close reason is never dropped.
      */
-    handleReconnect(reason) {
+    handleReconnect(error) {
+        const reason = typeof error === 'string'
+            ? error
+            : error instanceof Error
+                ? error.message
+                : undefined;
         if (reason !== undefined) {
             this.lastDisconnectReason = reason;
         }
@@ -1847,6 +1972,13 @@ class ConnectionManager {
             this.updateState('error', 'Automatic reconnection is disabled');
             return;
         }
+        if (error instanceof AreteError) {
+            const problem = error.apiProblem();
+            if (problem?.action || problem?.retryable === false) {
+                this.updateState('error', error.message);
+                return;
+            }
+        }
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             const lastReason = this.lastDisconnectReason;
             this.updateState('error', `Max reconnection attempts (${this.reconnectAttempts}) reached`
@@ -1855,14 +1987,18 @@ class ConnectionManager {
         }
         this.updateState('reconnecting', this.lastDisconnectReason);
         const attemptIndex = Math.min(this.reconnectAttempts, this.reconnectIntervals.length - 1);
-        const delay = this.reconnectIntervals[attemptIndex] ?? 1000;
+        const configuredDelay = this.reconnectIntervals[attemptIndex] ?? 1000;
+        const serverDelay = error instanceof AreteError
+            ? (error.retryAfter() ?? 0) * 1000
+            : 0;
+        const delay = Math.max(configuredDelay, serverDelay);
         this.reconnectAttempts++;
         this.reconnectTimeout = setTimeout(() => {
-            this.connect(true).catch((error) => {
+            this.connect(true).catch((connectError) => {
                 // Once a socket exists, its close event owns the next retry. Token
                 // acquisition and socket construction can fail before that point.
                 if (this.ws === null && this.currentState !== 'disconnected') {
-                    this.recoverFromFailedConnect(error);
+                    this.recoverFromFailedConnect(connectError);
                 }
             });
         }, delay);
@@ -1873,7 +2009,7 @@ class ConnectionManager {
             // connect() already reported the refusal as the terminal error state.
             return;
         }
-        this.handleReconnect(error instanceof Error ? error.message : undefined);
+        this.handleReconnect(error);
     }
     clearReconnectTimeout() {
         if (this.reconnectTimeout) {
@@ -8663,9 +8799,11 @@ function stringifyBigints(value) {
 
 const Arete = Object.assign(Arete$1, { session: createSession });
 
+exports.API_PROBLEM_SCHEMA_VERSION = API_PROBLEM_SCHEMA_VERSION;
 exports.ASSOCIATED_TOKEN_PROGRAM_ADDRESS = ASSOCIATED_TOKEN_PROGRAM_ADDRESS;
 exports.Arete = Arete;
 exports.AreteError = AreteError;
+exports.CLAIM_AGENT_MATERIALIZER_PATH = CLAIM_AGENT_MATERIALIZER_PATH;
 exports.ConnectionManager = ConnectionManager;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.DEFAULT_INITIAL_DATA_TIMEOUT_MS = DEFAULT_INITIAL_DATA_TIMEOUT_MS;
@@ -8751,10 +8889,12 @@ exports.getTransactionFailureOutcome = getTransactionFailureOutcome;
 exports.hostedWebsocketSuffixes = hostedWebsocketSuffixes;
 exports.inspectPreparedOperation = inspectPreparedOperation;
 exports.instructionOperation = instructionOperation;
+exports.isClaimAgentRecoveryAction = isClaimAgentRecoveryAction;
 exports.isEntityFrame = isEntityFrame;
 exports.isErrorFrame = isErrorFrame;
 exports.isHostedAreteEndpoint = isHostedAreteEndpoint;
 exports.isReplayErrorCode = isReplayErrorCode;
+exports.isSafeClaimActionUrl = isSafeClaimActionUrl;
 exports.isSameProgramSdk = isSameProgramSdk;
 exports.isSnapshotFrame = isSnapshotFrame;
 exports.isStackVersionRefusalCode = isStackVersionRefusalCode;
@@ -8766,6 +8906,7 @@ exports.normalizeSubscription = normalizeSubscription;
 exports.normalizeSubscriptionQuery = normalizeSubscriptionQuery;
 exports.normalizeSubscriptionRequest = normalizeSubscriptionRequest;
 exports.normalizeTransactionError = normalizeTransactionError;
+exports.parseApiProblem = parseApiProblem;
 exports.parseFrame = parseFrame;
 exports.parseFrameFromBlob = parseFrameFromBlob;
 exports.parseInstructionError = parseInstructionError;