@to11ai/sdk 0.1.0 → 0.1.2

package/dist/transport.d.ts

@@ -10,7 +10,12 @@ export interface TransportConfig {
     readonly auth: AuthConfig;
     /** Request timeout in milliseconds. Default: 30_000 */
     readonly timeoutMs?: number;
-    /** Max number of retries for network errors / 5xx (not counting the initial attempt). Default: 3 */
+    /**
+     * Max number of retries for network errors / 5xx on idempotent methods
+     * (GET/HEAD/OPTIONS/PUT/DELETE/TRACE per RFC 9110 §9.2.2). POST/PATCH are
+     * never auto-retried regardless of this value. Not counting the initial
+     * attempt. Default: 3
+     */
     readonly maxRetries?: number;
 }
 /** Standard API envelope returned by the to11ai server. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@to11ai/sdk",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"license": "MPL-2.0",
 	"type": "module",
 	"main": "./dist/client.cjs",

package/src/transport.ts

@@ -37,7 +37,12 @@ export interface TransportConfig {
 	readonly auth: AuthConfig;
 	/** Request timeout in milliseconds. Default: 30_000 */
 	readonly timeoutMs?: number;
-	/** Max number of retries for network errors / 5xx (not counting the initial attempt). Default: 3 */
+	/**
+	 * Max number of retries for network errors / 5xx on idempotent methods
+	 * (GET/HEAD/OPTIONS/PUT/DELETE/TRACE per RFC 9110 §9.2.2). POST/PATCH are
+	 * never auto-retried regardless of this value. Not counting the initial
+	 * attempt. Default: 3
+	 */
 	readonly maxRetries?: number;
 }
 
@@ -58,6 +63,22 @@ export interface ApiEnvelope<T = unknown> {
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 3;
 
+/**
+ * HTTP methods classified as idempotent by RFC 9110 §9.2.2. The SDK only
+ * auto-retries 5xx, network failures, and timeouts on these methods because
+ * a write that timed out or returned 5xx may have already committed on the
+ * server — replaying a non-idempotent method (POST/PATCH) can create
+ * duplicates or double-apply state.
+ */
+const IDEMPOTENT_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"PUT",
+	"DELETE",
+	"TRACE",
+]);
+
 /** Exponential backoff with jitter: 100ms * 2^attempt + random(0,100ms) */
 const backoffMs = (attempt: number): number =>
 	100 * 2 ** attempt + Math.random() * 100;
@@ -271,6 +292,7 @@ export class Transport {
 		},
 	): Promise<ApiEnvelope<T>> {
 		const url = new URL(this.baseUrl + path);
+		const isIdempotent = IDEMPOTENT_METHODS.has(method.toUpperCase());
 
 		if (options?.query) {
 			for (const [key, value] of Object.entries(options.query)) {
@@ -300,8 +322,14 @@ export class Transport {
 
 				clearTimeout(timeoutId);
 
-				// 5xx — retry if we have retries left
-				if (response.status >= 500 && attempt < this.maxRetries) {
+				// 5xx — retry only if the method is idempotent (RFC 9110 §9.2.2).
+				// POST/PATCH may have already committed server-side, so replaying
+				// them can create duplicates.
+				if (
+					response.status >= 500 &&
+					isIdempotent &&
+					attempt < this.maxRetries
+				) {
 					// Drain the body to free the underlying connection before sleeping
 					await response.body?.cancel().catch(() => undefined);
 					attempt++;
@@ -342,14 +370,21 @@ export class Transport {
 					throw err;
 				}
 
-				// Timeout / network errors — retry if retries remain
+				// Timeout / network errors — retry only if the method is idempotent
+				// (RFC 9110 §9.2.2). A POST/PATCH whose request body was fully sent
+				// before a connection drop or timeout may have committed server-side,
+				// so a replay can duplicate the write.
 				const isTimeout =
 					err instanceof DOMException && err.name === "AbortError";
 				// Only retry on genuine network failures (fetch throws TypeError) or timeouts.
 				// Unexpected errors (e.g. getAccessToken rejections) propagate immediately.
 				const isNetworkError = err instanceof TypeError;
 
-				if ((isTimeout || isNetworkError) && attempt < this.maxRetries) {
+				if (
+					(isTimeout || isNetworkError) &&
+					isIdempotent &&
+					attempt < this.maxRetries
+				) {
 					attempt++;
 					await sleep(backoffMs(attempt));
 					continue;