@expandai/sdk 0.17.2 → 0.18.0

package/src/Service.ts

@@ -1,6 +1,6 @@
 import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
 import { NodeHttpClient } from '@effect/platform-node'
-import { Context, Duration, Effect, flow, Layer, Schedule, Schema } from 'effect'
+import { Context, Duration, Effect, flow, Layer, Option, Random, Schedule, Schema } from 'effect'
 import { ExpandSdkError } from './Error.js'
 import {
 	type FetchObjectModeResultWithJson,
@@ -31,29 +31,28 @@ export class ExpandServiceOptions extends Schema.Class<ExpandServiceOptions>('Ex
 		}),
 		/**
 		 * Total wall-clock budget in milliseconds for the operation, including retries and backoff.
-		 * Each attempt gets `timeoutMs / (maxRetries + 1)`. Defaults to 60_000.
+		 * A successful attempt may use the remaining operation budget. Defaults to 60_000.
 		 */
 		timeoutMs: Schema.optional(Schema.Number).annotations({
 			description:
 				'Total wall-clock budget in milliseconds for the operation, including retries and backoff. ' +
-				'Each attempt gets `timeoutMs / (maxRetries + 1)`. Defaults to 60_000.',
+				'A successful attempt may use the remaining operation budget. Defaults to 60_000.',
 		}),
 		/**
 		 * Number of retry attempts for retryable failures (timeouts, connection errors, 408/409/429/5xx).
-		 * Defaults to 2. Note: `batched()` defaults to 0 regardless of this setting; pass `{ maxRetries: N }`
-		 * per-call to opt in.
+		 * Defaults to 2.
 		 */
 		maxRetries: Schema.optional(Schema.Number).annotations({
 			description:
 				'Number of retry attempts for retryable failures (timeouts, connection errors, 408/409/429/5xx). ' +
-				'Defaults to 2. Note: `batched()` defaults to 0 regardless of this setting; pass `{ maxRetries: N }` per-call to opt in.',
+				'Defaults to 2.',
 		}),
 	},
 	{ description: 'Options for constructing an `ExpandService` layer or `ExpandClient` instance.' },
 ) {}
 
 /**
- * Per-request overrides accepted by `ExpandService.fetch`/`batched`/`getBatched` (and, transitively,
+ * Per-request overrides accepted by `ExpandService.fetch`/`batched`/`getBatched`/`cancelBatched` (and, transitively,
  * by `ExpandClient`'s methods).
  */
 export class RequestOptions extends Schema.Class<RequestOptions>('RequestOptions')(
@@ -82,8 +81,12 @@ export type FetchSearchParams = typeof Generated.FetchFetchSearchRequest.Encoded
 export type FetchSearchResponse = FetchSnapshotSearchResultWithJson
 export type BatchedParams = typeof Generated.FetchBatchedRequest.Encoded
 export type BatchedResponse = typeof Generated.BatchedRun.Type
+export interface BatchedRequestOptions extends RequestOptions {
+	readonly idempotencyKey?: string
+}
 export type GetBatchedParams = typeof Generated.FetchGetBatchedParams.Encoded
 export type GetBatchedResponse = typeof Generated.BatchedStatus.Type
+export type CancelBatchedResponse = typeof Generated.BatchedCancellation.Type
 
 class ServiceConfig extends Schema.Class<ServiceConfig>('ExpandServiceConfig')({
 	apiKey: Schema.NonEmptyString,
@@ -175,20 +178,14 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 		) {
 			const totalTimeoutMs = requestOptions.timeoutMs ?? config.timeoutMs
 			const maxRetries = requestOptions.maxRetries ?? config.maxRetries
-			// `timeoutMs` is the wall-clock budget for the whole operation. Split it across attempts so the
-			// sum of per-attempt budgets equals `timeoutMs`; the outer Effect.timeout enforces the hard cap
-			// including retry backoff. Pipe ordering matters: per-attempt timeout must wrap the operation
-			// (so retry can catch its TimeoutException), and total timeout must wrap retry (so it caps
-			// backoff between attempts). Floor with a 1ms minimum so degenerate inputs don't produce a
-			// zero-millisecond budget that fires before any work happens.
-			const perAttemptTimeoutMs = Math.max(1, Math.floor(totalTimeoutMs / (maxRetries + 1)))
+			// `timeoutMs` is one wall-clock budget for the operation, including retries and backoff. A slow
+			// valid capture may use most of that budget; only failures that arrive before it expires can retry.
 			const retrySchedule = Schedule.exponential(Duration.millis(250)).pipe(
 				Schedule.jittered,
 				Schedule.compose(Schedule.recurs(maxRetries)),
 				Schedule.whileInput((error: unknown) => isRetryable(error, totalTimeoutMs)),
 			)
 			return yield* operation.pipe(
-				Effect.timeout(Duration.millis(perAttemptTimeoutMs)),
 				Effect.retry(retrySchedule),
 				Effect.timeout(Duration.millis(totalTimeoutMs)),
 				Effect.mapError((error) => toExpandError(error, totalTimeoutMs)),
@@ -226,15 +223,26 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 
 		const batched = Effect.fn('ExpandService.batched')(function* (
 			params: BatchedParams,
-			requestOptions: RequestOptions = {},
+			requestOptions: BatchedRequestOptions = {},
 		) {
-			// Batched POST kicks off server-side work and the API has no idempotency-key support; a retry on
-			// a request that succeeded server-side but failed client-side (timeout, dropped connection)
-			// would create a duplicate batched run. Default to no retries; callers can opt in explicitly.
-			// Destructure-with-default also handles `{ maxRetries: undefined }` correctly — falls back to 0
-			// rather than the service-level default.
-			const { maxRetries = 0, ...rest } = requestOptions
-			return yield* withRetries(generated.fetchBatched(params), { maxRetries, ...rest })
+			const { idempotencyKey: providedIdempotencyKey, ...retryOptions } = requestOptions
+			const idempotencyKey = yield* Option.fromNullable(providedIdempotencyKey).pipe(
+				Option.match({
+					onSome: Effect.succeed,
+					onNone: () =>
+						Effect.all([Random.nextInt, Random.nextInt, Random.nextInt]).pipe(
+							Effect.map(
+								([first, second, third]) =>
+									`sdk-${Math.abs(first).toString(36)}-${Math.abs(second).toString(36)}-${Math.abs(third).toString(36)}`,
+							),
+						),
+				}),
+			)
+			const generatedRequest: Parameters<typeof generated.fetchBatched>[0] = {
+				params: { 'x-idempotency-key': idempotencyKey },
+				payload: params,
+			}
+			return yield* withRetries(generated.fetchBatched(generatedRequest), retryOptions)
 		})
 
 		const getBatched = Effect.fn('ExpandService.getBatched')(function* (
@@ -247,7 +255,14 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 			return yield* withRetries(generated.fetchGetBatched(id, params), { timeoutMs, maxRetries })
 		})
 
-		return { fetch, fetchJson, fetchSearch, batched, getBatched } as const
+		const cancelBatched = Effect.fn('ExpandService.cancelBatched')(function* (
+			id: string,
+			requestOptions: RequestOptions = {},
+		) {
+			return yield* withRetries(generated.fetchCancelBatched(id), requestOptions)
+		})
+
+		return { fetch, fetchJson, fetchSearch, batched, getBatched, cancelBatched } as const
 	}),
 }) {
 	/**

package/src/index.ts

@@ -1,6 +1,8 @@
 export type {
 	BatchedParams,
+	BatchedRequestOptions,
 	BatchedResponse,
+	CancelBatchedResponse,
 	ExpandClientOptions,
 	FetchJsonParams,
 	FetchJsonRequestOptions,