@to11ai/sdk 0.0.2 → 0.1.1

package/src/transport.ts

@@ -1,10 +1,32 @@
 import {
+	EnvNotEnabledForProviderError,
+	NoApplicableRouteError,
+	PromptLabelNotRegisteredError,
+	RuleNotFoundError,
+	RuleVersionInvalidSnapshotError,
 	To11aiApiError,
 	To11aiAuthError,
 	To11aiNetworkError,
 	To11aiRateLimitError,
 	To11aiValidationError,
 } from "./errors";
+import { activeTraceContext } from "./traceparent";
+
+const INVALID_SNAPSHOT_ERROR_CODES = new Set([
+	"INVALID_VARIANT_PARAMS",
+	"INVALID_VARIANT_WEIGHTS",
+	"INVALID_RULE_STRATEGY",
+	"INVALID_STEP_COUNT",
+	"RULE_ENDPOINT_MISMATCH",
+	"INVALID_WHEN_CLAUSE",
+	"INVALID_STRATEGY_VARIANTS",
+	"INVALID_RETRY_POLICY",
+]);
+
+const RULE_NOT_FOUND_DETAILS_ERRORS = new Set([
+	"rule_not_found",
+	"rule_not_found_in_env",
+]);
 
 export type AuthConfig =
 	| { readonly apiKey: string; readonly getAccessToken?: never }
@@ -15,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;
 }
 
@@ -36,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;
@@ -76,9 +119,132 @@ function mapHttpError(
 			details,
 		);
 	}
+	if (
+		(status === 400 || status === 422) &&
+		errorCode &&
+		INVALID_SNAPSHOT_ERROR_CODES.has(errorCode)
+	) {
+		const d = (details && typeof details === "object" ? details : {}) as Record<
+			string,
+			unknown
+		>;
+		return new RuleVersionInvalidSnapshotError(
+			message,
+			errorCode,
+			{
+				field: typeof d.field === "string" ? d.field : undefined,
+				reason: typeof d.reason === "string" ? d.reason : undefined,
+				variantName:
+					typeof d.variantName === "string" ? d.variantName : undefined,
+			},
+			details,
+			status,
+		);
+	}
 	if (status === 400) {
 		return new To11aiValidationError(message, errorCode, details);
 	}
+	if (status === 404) {
+		const d = (details && typeof details === "object" ? details : {}) as Record<
+			string,
+			unknown
+		>;
+		const detailsError = typeof d.error === "string" ? d.error : undefined;
+		const isRuleNotFound =
+			errorCode === "RULE_NOT_FOUND" ||
+			errorCode === "RULE_NOT_FOUND_IN_ENV" ||
+			(detailsError !== undefined &&
+				RULE_NOT_FOUND_DETAILS_ERRORS.has(detailsError));
+		if (isRuleNotFound) {
+			const resolvedCode =
+				errorCode === "RULE_NOT_FOUND" || errorCode === "RULE_NOT_FOUND_IN_ENV"
+					? errorCode
+					: detailsError === "rule_not_found_in_env"
+						? "RULE_NOT_FOUND_IN_ENV"
+						: "RULE_NOT_FOUND";
+			return new RuleNotFoundError(
+				message,
+				resolvedCode,
+				{
+					ruleId: typeof d.ruleId === "string" ? d.ruleId : undefined,
+					model: typeof d.model === "string" ? d.model : undefined,
+					env: typeof d.env === "string" ? d.env : undefined,
+				},
+				details,
+			);
+		}
+	}
+	if (status === 422 && errorCode === "NO_APPLICABLE_ROUTE") {
+		const d = (details && typeof details === "object" ? details : {}) as Record<
+			string,
+			unknown
+		>;
+		const ruleId =
+			typeof d.rule === "string"
+				? d.rule
+				: typeof d.ruleId === "string"
+					? d.ruleId
+					: "";
+		const versionId =
+			typeof d.version === "string"
+				? d.version
+				: typeof d.versionId === "string"
+					? d.versionId
+					: "";
+		return new NoApplicableRouteError(
+			message,
+			{
+				ruleId,
+				versionId,
+				reason: typeof d.reason === "string" ? d.reason : "",
+			},
+			details,
+		);
+	}
+	if (status === 422 && errorCode === "ENV_NOT_ENABLED_FOR_PROVIDER") {
+		const d = (details && typeof details === "object" ? details : {}) as Record<
+			string,
+			unknown
+		>;
+		const ruleId =
+			typeof d.rule === "string"
+				? d.rule
+				: typeof d.ruleId === "string"
+					? d.ruleId
+					: "";
+		const envSlug =
+			typeof d.env === "string"
+				? d.env
+				: typeof d.envSlug === "string"
+					? d.envSlug
+					: "";
+		return new EnvNotEnabledForProviderError(
+			message,
+			{
+				ruleId,
+				envSlug,
+				providerId: typeof d.providerId === "string" ? d.providerId : "",
+			},
+			details,
+		);
+	}
+	if (status === 422 && errorCode === "PROMPT_LABEL_NOT_REGISTERED") {
+		// TO11-664: strict-mode rejection. Pull projectId / label out of the
+		// structured `details` payload the API attaches so call sites can use
+		// the typed attributes without re-parsing.
+		const d = (details && typeof details === "object" ? details : {}) as Record<
+			string,
+			unknown
+		>;
+		const projectId = typeof d.projectId === "string" ? d.projectId : "";
+		const label = typeof d.label === "string" ? d.label : "";
+		return new PromptLabelNotRegisteredError(
+			message,
+			projectId,
+			label,
+			details,
+		);
+	}
 	return new To11aiApiError(message, status, errorCode, details);
 }
 
@@ -108,6 +274,12 @@ export class Transport {
 			headers.authorization = `Bearer ${token}`;
 		}
 
+		const tp = activeTraceContext();
+		if (tp) {
+			headers.traceparent = tp.traceparent;
+			if (tp.tracestate) headers.tracestate = tp.tracestate;
+		}
+
 		return headers;
 	}
 
@@ -120,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)) {
@@ -149,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++;
@@ -191,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;