@expandai/sdk 0.17.2 → 0.18.0

package/src/Generated.ts

@@ -27,15 +27,6 @@ export class FetchFetchRequest extends S.Class<FetchFetchRequest>('FetchFetchReq
 				),
 				{ nullable: true },
 			),
-			summary: S.optionalWith(
-				S.Union(
-					S.Boolean,
-					S.Struct({
-						prompt: S.optionalWith(S.String.pipe(S.maxLength(5000)), { nullable: true }),
-					}),
-				),
-				{ nullable: true },
-			),
 			links: S.optionalWith(
 				S.Union(
 					S.Boolean,
@@ -165,10 +156,24 @@ export class FetchFetch403 extends S.Union(
 
 export class PayloadTooLargeTag extends S.Literal('PayloadTooLarge') {}
 
-export class PayloadTooLarge extends S.Class<PayloadTooLarge>('PayloadTooLarge')({
+export class PayloadTooLarge extends S.Struct({
 	_tag: PayloadTooLargeTag,
 }) {}
 
+export class FetchPageTooLargeLimitKind extends S.Literal('transfer_bytes', 'domsnapshot_bytes', 'ast_bytes') {}
+
+export class FetchPageTooLargeTag extends S.Literal('FetchPageTooLarge') {}
+
+export class FetchPageTooLarge extends S.Struct({
+	url: S.String,
+	limitKind: S.optionalWith(FetchPageTooLargeLimitKind, { nullable: true }),
+	limitBytes: S.optionalWith(S.Number, { nullable: true }),
+	measuredBytes: S.optionalWith(S.Number, { nullable: true }),
+	_tag: FetchPageTooLargeTag,
+}) {}
+
+export class FetchFetch413 extends S.Union(PayloadTooLarge, FetchPageTooLarge) {}
+
 export class TooManyRequestsTag extends S.Literal('TooManyRequests') {}
 
 export class TooManyRequests extends S.Class<TooManyRequests>('TooManyRequests')({
@@ -184,6 +189,8 @@ export class InternalError extends S.Class<InternalError>('InternalError')({
 export class ServiceUnavailableTag extends S.Literal('ServiceUnavailable') {}
 
 export class ServiceUnavailable extends S.Class<ServiceUnavailable>('ServiceUnavailable')({
+	message: S.optionalWith(S.String, { nullable: true }),
+	requestId: S.optionalWith(S.String, { nullable: true }),
 	_tag: ServiceUnavailableTag,
 }) {}
 
@@ -206,15 +213,6 @@ export class FetchFetchJsonRequest extends S.Class<FetchFetchJsonRequest>('Fetch
 				),
 				{ nullable: true },
 			),
-			summary: S.optionalWith(
-				S.Union(
-					S.Boolean,
-					S.Struct({
-						prompt: S.optionalWith(S.String.pipe(S.maxLength(5000)), { nullable: true }),
-					}),
-				),
-				{ nullable: true },
-			),
 			links: S.optionalWith(
 				S.Union(
 					S.Boolean,
@@ -344,33 +342,10 @@ export class FetchAssetReference extends S.Struct({
 	bytes: S.Number,
 }) {}
 
-export class CaptureTelemetryInfoRequestedStyleMode extends S.Literal('compat_full', 'native_default') {}
-
-export class CaptureTelemetryInfoSelected extends S.Literal('rust') {}
-
-export class CaptureTelemetryInfoActual extends S.Literal('rust') {}
-
-export class CaptureTelemetryInfoActualStyleMode extends S.Literal('compat_full', 'native_default') {}
-
-export class CaptureTelemetryInfoIconBackendDecision extends S.Literal('cpu', 'remote_gpu') {}
-
-export class CaptureTelemetryInfo extends S.Struct({
-	requestedStyleMode: S.optionalWith(CaptureTelemetryInfoRequestedStyleMode, { nullable: true }),
-	selected: CaptureTelemetryInfoSelected,
-	actual: CaptureTelemetryInfoActual,
-	actualStyleMode: S.optionalWith(CaptureTelemetryInfoActualStyleMode, { nullable: true }),
-	rolloutApplied: S.Boolean,
-	preparedSessionHit: S.optionalWith(S.Boolean, { nullable: true }),
-	nativePoolHit: S.optionalWith(S.Boolean, { nullable: true }),
-	nativePoolCapacity: S.optionalWith(S.Number, { nullable: true }),
-	nativePoolProfile: S.optionalWith(S.String, { nullable: true }),
-	poolHit: S.optionalWith(S.Boolean, { nullable: true }),
-	connectMs: S.optionalWith(S.Number, { nullable: true }),
-	warmConnectionAgeMs: S.optionalWith(S.Number, { nullable: true }),
-	iconBackendDecision: S.optionalWith(CaptureTelemetryInfoIconBackendDecision, { nullable: true }),
-}) {}
+export class Int extends S.Int {}
 
 export class FetchSearchSnippetLocation extends S.Struct({
+	evidenceId: S.optionalWith(Int, { nullable: true }),
 	markdownBlockId: S.optionalWith(S.String, { nullable: true }),
 	nodeIds: S.optionalWith(S.Array(S.Number), { nullable: true }),
 	stateJsonSourceId: S.optionalWith(S.Number, { nullable: true }),
@@ -419,7 +394,6 @@ export class FetchObjectModeResult extends S.Class<FetchObjectModeResult>('Fetch
 	data: S.optionalWith(
 		S.Struct({
 			assets: S.optionalWith(S.Array(FetchAssetReference), { nullable: true }),
-			captureTelemetry: S.optionalWith(CaptureTelemetryInfo, { nullable: true }),
 			search: S.optionalWith(FetchSearchResult, { nullable: true }),
 			screenshot: S.optionalWith(
 				S.Struct({
@@ -444,13 +418,7 @@ export class FetchFetchJson403 extends S.Union(
 	FetchBlocked,
 ) {}
 
-export class IncludeHtmlConfig extends S.Record({ key: S.String, value: S.Unknown }) {}
-
-export class IncludeMarkdownConfig extends S.Record({ key: S.String, value: S.Unknown }) {}
-
-export class IncludeScreenshotConfig extends S.Struct({
-	fullPage: S.optionalWith(S.Boolean, { nullable: true }),
-}) {}
+export class FetchFetchJson413 extends S.Union(PayloadTooLarge, FetchPageTooLarge) {}
 
 export class FetchFetchSearchRequest extends S.Class<FetchFetchSearchRequest>('FetchFetchSearchRequest')({
 	snapshotId: S.String.pipe(S.minLength(1)),
@@ -467,18 +435,13 @@ export class FetchFetchSearchRequest extends S.Class<FetchFetchSearchRequest>('F
 	}),
 	include: S.optionalWith(
 		S.Struct({
-			html: S.optionalWith(S.Union(S.Boolean, IncludeHtmlConfig), { nullable: true }),
-			markdown: S.optionalWith(S.Union(S.Boolean, IncludeMarkdownConfig), { nullable: true }),
-			screenshot: S.optionalWith(S.Union(S.Boolean, IncludeScreenshotConfig), { nullable: true }),
-			summary: S.optionalWith(
+			html: S.optionalWith(S.Union(S.Boolean, S.Record({ key: S.String, value: S.Unknown })), { nullable: true }),
+			markdown: S.optionalWith(S.Union(S.Boolean, S.Record({ key: S.String, value: S.Unknown })), { nullable: true }),
+			screenshot: S.optionalWith(
 				S.Union(
 					S.Boolean,
 					S.Struct({
-						prompt: S.optionalWith(S.String.pipe(S.maxLength(5000)), {
-							nullable: true,
-							default: () =>
-								'You are a helpful assistant that summarizes web page content.\nGiven the markdown content of a web page, provide a clear and concise summary.\nFocus on the main points and key information.\nKeep the summary informative but brief.' as const,
-						}),
+						fullPage: S.optionalWith(S.Boolean, { nullable: true }),
 					}),
 				),
 				{ nullable: true },
@@ -523,6 +486,7 @@ export class FetchSnapshotSearchResult extends S.Class<FetchSnapshotSearchResult
 	response: ResponseInfo,
 	search: FetchSearchResult,
 	durationMs: S.Number.pipe(S.greaterThanOrEqualTo(0)),
+	playground: S.String,
 }) {}
 
 export class FetchFetchSearch400 extends S.Union(HttpApiDecodeError, BadRequest) {}
@@ -544,22 +508,21 @@ export class FetchSnapshotSearchNotFound extends S.Class<FetchSnapshotSearchNotF
 	_tag: FetchSnapshotSearchNotFoundTag,
 }) {}
 
+export class FetchBatchedParams extends S.Struct({
+	'x-idempotency-key': S.optionalWith(S.String.pipe(S.minLength(1), S.maxLength(255)), { nullable: true }),
+}) {}
+
 export class FetchBatchedRequest extends S.Class<FetchBatchedRequest>('FetchBatchedRequest')({
 	urls: S.NonEmptyArray(S.String),
 	include: S.optionalWith(
 		S.Struct({
-			html: S.optionalWith(S.Union(S.Boolean, IncludeHtmlConfig), { nullable: true }),
-			markdown: S.optionalWith(S.Union(S.Boolean, IncludeMarkdownConfig), { nullable: true }),
-			screenshot: S.optionalWith(S.Union(S.Boolean, IncludeScreenshotConfig), { nullable: true }),
-			summary: S.optionalWith(
+			html: S.optionalWith(S.Union(S.Boolean, S.Record({ key: S.String, value: S.Unknown })), { nullable: true }),
+			markdown: S.optionalWith(S.Union(S.Boolean, S.Record({ key: S.String, value: S.Unknown })), { nullable: true }),
+			screenshot: S.optionalWith(
 				S.Union(
 					S.Boolean,
 					S.Struct({
-						prompt: S.optionalWith(S.String.pipe(S.maxLength(5000)), {
-							nullable: true,
-							default: () =>
-								'You are a helpful assistant that summarizes web page content.\nGiven the markdown content of a web page, provide a clear and concise summary.\nFocus on the main points and key information.\nKeep the summary informative but brief.' as const,
-						}),
+						fullPage: S.optionalWith(S.Boolean, { nullable: true }),
 					}),
 				),
 				{ nullable: true },
@@ -609,15 +572,41 @@ export class FetchBatched403 extends S.Struct({
 	_tag: FetchBatched403Tag,
 }) {}
 
+export class BatchedIdempotencyConflictReason extends S.Literal('payload_mismatch') {}
+
+export class BatchedIdempotencyConflictTag extends S.Literal('BatchedIdempotencyConflict') {}
+
+export class BatchedIdempotencyConflict extends S.Class<BatchedIdempotencyConflict>('BatchedIdempotencyConflict')({
+	existingRunId: S.String,
+	reason: BatchedIdempotencyConflictReason,
+	_tag: BatchedIdempotencyConflictTag,
+}) {}
+
 export class FetchGetBatchedParams extends S.Struct({
 	limit: S.optionalWith(S.String, { nullable: true }),
 	offset: S.optionalWith(S.String, { nullable: true }),
 	include: S.optionalWith(S.String, { nullable: true }),
 }) {}
 
-export class BatchedStatusStatus extends S.Literal('QUEUED', 'RUNNING', 'COMPLETED', 'FAILED', 'CANCELLED') {}
+export class BatchedStatusStatus extends S.Literal(
+	'QUEUED',
+	'RUNNING',
+	'CANCELLING',
+	'COMPLETED',
+	'FAILED',
+	'CANCELLED',
+) {}
 
-export class BatchedStatusBatchedStatus extends S.Literal('QUEUED', 'RUNNING', 'COMPLETED', 'FAILED', 'CANCELLED') {}
+export class BatchedStatusBatchedStatus extends S.Literal(
+	'QUEUED',
+	'RUNNING',
+	'CANCELLING',
+	'COMPLETED',
+	'FAILED',
+	'CANCELLED',
+) {}
+
+export class BatchedFetchItemStatus extends S.Literal('QUEUED', 'RUNNING', 'SUCCEEDED', 'FAILED', 'CANCELLED') {}
 
 export class IconMeta extends S.Struct({
 	href: S.String.pipe(S.minLength(1)),
@@ -681,6 +670,34 @@ export class RenderEnginesInfo extends S.Struct({
 	tree: S.optionalWith(RenderEnginesInfoTree, { nullable: true }),
 }) {}
 
+export class BatchedFetchItem extends S.Struct({
+	status: BatchedFetchItemStatus,
+	data: S.optionalWith(
+		S.Struct({
+			response: ResponseInfo,
+			meta: S.optionalWith(PageMeta, { nullable: true }),
+			json: S.optionalWith(S.Array(S.Struct({})), { nullable: true }),
+			snapshotId: S.optionalWith(NonEmptyString, { nullable: true }),
+			html: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
+			markdown: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
+			screenshot: S.optionalWith(
+				S.Struct({
+					url: S.String,
+					fullPage: S.Boolean,
+				}),
+				{ nullable: true },
+			),
+			search: S.optionalWith(FetchSearchResult, { nullable: true }),
+			links: S.optionalWith(S.Array(FetchLink), { nullable: true }),
+			appendix: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
+			renderEngines: S.optionalWith(RenderEnginesInfo, { nullable: true }),
+			assets: S.optionalWith(S.Array(FetchAssetReference), { nullable: true }),
+		}),
+		{ nullable: true },
+	),
+	error: S.optionalWith(S.Union(FetchBlocked, FetchPageTooLarge), { nullable: true }),
+}) {}
+
 export class PaginationMeta extends S.Struct({
 	total: S.Number,
 	limit: S.Number,
@@ -693,38 +710,7 @@ export class BatchedStatus extends S.Class<BatchedStatus>('BatchedStatus')({
 	status: BatchedStatusStatus,
 	batchedStatus: BatchedStatusBatchedStatus,
 	totalUrls: S.Number,
-	results: S.Array(
-		S.Struct({
-			data: S.Struct({
-				response: ResponseInfo,
-				meta: S.optionalWith(PageMeta, { nullable: true }),
-				json: S.optionalWith(S.Array(S.Struct({})), { nullable: true }),
-				snapshotId: S.optionalWith(NonEmptyString, { nullable: true }),
-				html: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
-				markdown: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
-				screenshot: S.optionalWith(
-					S.Struct({
-						url: S.String,
-						fullPage: S.Boolean,
-					}),
-					{ nullable: true },
-				),
-				summary: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
-				search: S.optionalWith(FetchSearchResult, { nullable: true }),
-				links: S.optionalWith(S.Array(FetchLink), { nullable: true }),
-				appendix: S.optionalWith(S.String.pipe(S.minLength(1)), { nullable: true }),
-				renderEngines: S.optionalWith(RenderEnginesInfo, { nullable: true }),
-				captureTelemetry: S.optionalWith(CaptureTelemetryInfo, { nullable: true }),
-				assets: S.optionalWith(S.Array(FetchAssetReference), { nullable: true }),
-				blocked: S.optionalWith(
-					S.Struct({
-						blockedType: S.optionalWith(S.String, { nullable: true }),
-					}),
-					{ nullable: true },
-				),
-			}),
-		}),
-	),
+	results: S.Array(BatchedFetchItem),
 	pagination: PaginationMeta,
 }) {}
 
@@ -737,6 +723,23 @@ export class BatchedIncludeUnsupported extends S.Struct({
 
 export class FetchGetBatched400 extends S.Union(HttpApiDecodeError, BatchedIncludeUnsupported) {}
 
+export class BatchedCancellationStatus extends S.Literal('CANCELLING', 'CANCELLED') {}
+
+export class BatchedCancellation extends S.Class<BatchedCancellation>('BatchedCancellation')({
+	id: S.String,
+	status: BatchedCancellationStatus,
+}) {}
+
+export class BatchedCancellationConflictStatus extends S.Literal('COMPLETED', 'FAILED') {}
+
+export class BatchedCancellationConflictTag extends S.Literal('BatchedCancellationConflict') {}
+
+export class BatchedCancellationConflict extends S.Class<BatchedCancellationConflict>('BatchedCancellationConflict')({
+	id: S.String,
+	status: BatchedCancellationConflictStatus,
+	_tag: BatchedCancellationConflictTag,
+}) {}
+
 export const make = (
 	httpClient: HttpClient.HttpClient,
 	options: {
@@ -776,7 +779,7 @@ export const make = (
 								'400': (r) => decodeError(r, FetchFetch400),
 								'401': (r) => decodeError(r, AuthFailed),
 								'403': (r) => decodeError(r, FetchFetch403),
-								'413': (r) => decodeError(r, PayloadTooLarge),
+								'413': (r) => decodeError(r, FetchFetch413),
 								'429': (r) => decodeError(r, TooManyRequests),
 								'500': (r) => decodeError(r, InternalError),
 								'503': (r) => decodeError(r, ServiceUnavailable),
@@ -799,7 +802,7 @@ export const make = (
 								'400': (r) => decodeError(r, FetchFetchJson400),
 								'401': (r) => decodeError(r, AuthFailed),
 								'403': (r) => decodeError(r, FetchFetchJson403),
-								'413': (r) => decodeError(r, PayloadTooLarge),
+								'413': (r) => decodeError(r, FetchFetchJson413),
 								'429': (r) => decodeError(r, TooManyRequests),
 								'500': (r) => decodeError(r, InternalError),
 								'503': (r) => decodeError(r, ServiceUnavailable),
@@ -834,7 +837,8 @@ export const make = (
 			),
 		fetchBatched: (options) =>
 			HttpClientRequest.make('POST')(`/v1/fetch/batched`).pipe(
-				(req) => Effect.orDie(HttpClientRequest.bodyJson(req, options)),
+				HttpClientRequest.setHeaders({ 'x-idempotency-key': options.params['x-idempotency-key'] ?? undefined }),
+				(req) => Effect.orDie(HttpClientRequest.bodyJson(req, options.payload)),
 				Effect.flatMap((request) =>
 					Effect.flatMap(applyClientTransform(httpClient), (httpClient) =>
 						Effect.flatMap(
@@ -844,6 +848,7 @@ export const make = (
 								'400': (r) => decodeError(r, FetchBatched400),
 								'401': (r) => decodeError(r, AuthFailed),
 								'403': (r) => decodeError(r, FetchBatched403),
+								'409': (r) => decodeError(r, BatchedIdempotencyConflict),
 								'413': (r) => decodeError(r, PayloadTooLarge),
 								'429': (r) => decodeError(r, TooManyRequests),
 								'500': (r) => decodeError(r, InternalError),
@@ -880,6 +885,28 @@ export const make = (
 					),
 				),
 			),
+		fetchCancelBatched: (id) =>
+			HttpClientRequest.make('POST')(`/v1/fetch/batched/${id}/cancel`).pipe(
+				Effect.succeed,
+				Effect.flatMap((request) =>
+					Effect.flatMap(applyClientTransform(httpClient), (httpClient) =>
+						Effect.flatMap(
+							httpClient.execute(request),
+							HttpClientResponse.matchStatus({
+								'200': (r) => HttpClientResponse.schemaBodyJson(BatchedCancellation)(r),
+								'400': (r) => decodeError(r, HttpApiDecodeError),
+								'401': (r) => decodeError(r, AuthFailed),
+								'409': (r) => decodeError(r, BatchedCancellationConflict),
+								'413': (r) => decodeError(r, PayloadTooLarge),
+								'429': (r) => decodeError(r, TooManyRequests),
+								'500': (r) => decodeError(r, InternalError),
+								'503': (r) => decodeError(r, ServiceUnavailable),
+								orElse: (response) => unexpectedStatus(request, response),
+							}),
+						),
+					),
+				),
+			),
 	}
 }
 
@@ -894,7 +921,7 @@ export interface Client {
 		| typeof FetchFetch400.Type
 		| typeof AuthFailed.Type
 		| typeof FetchFetch403.Type
-		| typeof PayloadTooLarge.Type
+		| typeof FetchFetch413.Type
 		| typeof TooManyRequests.Type
 		| typeof InternalError.Type
 		| typeof ServiceUnavailable.Type
@@ -909,7 +936,7 @@ export interface Client {
 		| typeof FetchFetchJson400.Type
 		| typeof AuthFailed.Type
 		| typeof FetchFetchJson403.Type
-		| typeof PayloadTooLarge.Type
+		| typeof FetchFetchJson413.Type
 		| typeof TooManyRequests.Type
 		| typeof InternalError.Type
 		| typeof ServiceUnavailable.Type
@@ -929,15 +956,17 @@ export interface Client {
 		| typeof InternalError.Type
 		| typeof ServiceUnavailable.Type
 	>
-	readonly fetchBatched: (
-		options: typeof FetchBatchedRequest.Encoded,
-	) => Effect.Effect<
+	readonly fetchBatched: (options: {
+		readonly params: typeof FetchBatchedParams.Encoded
+		readonly payload: typeof FetchBatchedRequest.Encoded
+	}) => Effect.Effect<
 		typeof BatchedRun.Type,
 		| HttpClientError.HttpClientError
 		| ParseError
 		| typeof FetchBatched400.Type
 		| typeof AuthFailed.Type
 		| typeof FetchBatched403.Type
+		| typeof BatchedIdempotencyConflict.Type
 		| typeof PayloadTooLarge.Type
 		| typeof TooManyRequests.Type
 		| typeof InternalError.Type
@@ -957,4 +986,18 @@ export interface Client {
 		| typeof InternalError.Type
 		| typeof ServiceUnavailable.Type
 	>
+	readonly fetchCancelBatched: (
+		id: string,
+	) => Effect.Effect<
+		typeof BatchedCancellation.Type,
+		| HttpClientError.HttpClientError
+		| ParseError
+		| typeof HttpApiDecodeError.Type
+		| typeof AuthFailed.Type
+		| typeof BatchedCancellationConflict.Type
+		| typeof PayloadTooLarge.Type
+		| typeof TooManyRequests.Type
+		| typeof InternalError.Type
+		| typeof ServiceUnavailable.Type
+	>
 }

package/src/Internal.ts

@@ -11,7 +11,9 @@ import {
 import * as Generated from './Generated.js'
 import {
 	type BatchedParams,
+	type BatchedRequestOptions,
 	type BatchedResponse,
+	type CancelBatchedResponse,
 	ExpandService,
 	type ExpandServiceOptions,
 	type FetchJsonParams,
@@ -37,9 +39,15 @@ function hasApiErrorTag(error: unknown, tag: string): error is TaggedApiError {
 
 function apiError(status: number, error: unknown): ExpandApiError {
 	const message =
-		typeof error === 'object' && error !== null && '_tag' in error && typeof error._tag === 'string'
-			? error._tag
-			: `HTTP ${status}`
+		typeof error === 'object' &&
+		error !== null &&
+		'message' in error &&
+		typeof error.message === 'string' &&
+		error.message.length > 0
+			? error.message
+			: typeof error === 'object' && error !== null && '_tag' in error && typeof error._tag === 'string'
+				? error._tag
+				: `HTTP ${status}`
 	return new ExpandApiError({ message, status, body: error, cause: error })
 }
 
@@ -80,6 +88,11 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 			(error: unknown) => hasApiErrorTag(error, 'AccessBlocked'),
 			(error) => apiError(403, error),
 		),
+		Match.when(
+			(error: unknown) =>
+				hasApiErrorTag(error, 'BatchedIdempotencyConflict') || hasApiErrorTag(error, 'BatchedCancellationConflict'),
+			(error) => apiError(409, error),
+		),
 		Match.when(
 			(error: unknown) => error instanceof Generated.PayloadTooLarge,
 			(error) => new ExpandApiError({ message: 'PayloadTooLarge', status: 413, body: error, cause: error }),
@@ -106,7 +119,7 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 		),
 		Match.when(
 			(error: unknown) => error instanceof Generated.ServiceUnavailable,
-			(error) => new ExpandApiError({ message: 'ServiceUnavailable', status: 503, body: error, cause: error }),
+			(error) => apiError(503, error),
 		),
 		Match.when(
 			(error: unknown) => hasApiErrorTag(error, 'ServiceUnavailable'),
@@ -142,6 +155,9 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
  * retryable; API errors are retryable only for the standard transient status codes (408/409/429/5xx).
  */
 export function isRetryable(error: unknown, timeoutMs: number): boolean {
+	if (hasApiErrorTag(error, 'BatchedIdempotencyConflict') || hasApiErrorTag(error, 'BatchedCancellationConflict')) {
+		return false
+	}
 	// An undecodable response (a transient 5xx with an empty/garbled body, a proxy error page, etc.)
 	// surfaces as a bare ParseError with no HTTP status, so the status-based classification below can't
 	// see the 5xx and the request would fail un-retried. Treat decode failures as retryable — the
@@ -170,7 +186,7 @@ export function isRetryable(error: unknown, timeoutMs: number): boolean {
 /**
  * Effect-side bridge between {@link ExpandService} and the Promise-based {@link ExpandClient}.
  *
- * Exposes the same fetch/batched/getBatched methods as `ExpandService` but with the typed `ExpandError`
+ * Exposes the same fetch/batched/getBatched/cancelBatched methods as `ExpandService` but with the typed `ExpandError`
  * channel mapped to the `ExpandClientError` hierarchy that async/await consumers expect. Not exported
  * from the package — Effect consumers depend on `ExpandService` directly and receive the typed
  * `ExpandError` unions as-is.
@@ -199,7 +215,7 @@ export class InternalClient extends Effect.Service<InternalClient>()('@expandai/
 
 		const batched = (
 			params: BatchedParams,
-			options: RequestOptions = {},
+			options: BatchedRequestOptions,
 		): Effect.Effect<BatchedResponse, ExpandClientError> =>
 			service.batched(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
 
@@ -209,7 +225,13 @@ export class InternalClient extends Effect.Service<InternalClient>()('@expandai/
 		): Effect.Effect<GetBatchedResponse, ExpandClientError> =>
 			service.getBatched(id, options).pipe(Effect.mapError((error) => error.toPublicError()))
 
-		return { fetch, fetchJson, fetchSearch, batched, getBatched } as const
+		const cancelBatched = (
+			id: string,
+			options: RequestOptions = {},
+		): Effect.Effect<CancelBatchedResponse, ExpandClientError> =>
+			service.cancelBatched(id, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		return { fetch, fetchJson, fetchSearch, batched, getBatched, cancelBatched } as const
 	}),
 }) {
 	/**

package/src/Playground.ts

@@ -3,12 +3,9 @@
 // Canonical public snapshot URLs (all public, no auth, no TTL):
 //
 //   /s/<snapshotId>                          — whole snapshot
-//   /s/<snapshotId>/playground#focus=<id>    — highlight a markdown/appendix block by node id
-//   /s/<snapshotId>?id=<evidenceId>          — open extracted State JSON evidence
+//   /s/<snapshotId>?id=<evidenceId>          — open any public evidence target
 //
-// A citation maps a search snippet (`source` + `location`) to the view that audits it.
-
-import { Match } from 'effect'
+// A citation maps a search snippet location to the view that audits it.
 
 export const DEFAULT_PLAYGROUND_HOST = 'https://expand.land'
 
@@ -16,7 +13,12 @@ export type CitationSource = 'markdown' | 'appendix' | 'statejson'
 
 /** Snippet location subset needed to build a deep link. Tolerates `null` and `undefined`. */
 export interface CitationLocation {
+	readonly evidenceId?: number | null
+	/** @deprecated Use evidenceId. */
+	readonly markdownBlockId?: string | null
+	/** @deprecated Use evidenceId for public citations. */
 	readonly nodeIds?: ReadonlyArray<number> | null
+	/** @deprecated Use evidenceId. */
 	readonly stateJsonSourceId?: number | null
 }
 
@@ -24,6 +26,18 @@ function normalizeHost(host: string): string {
 	return host.replace(/\/+$/, '')
 }
 
+function publicEvidenceId(value: number | null | undefined): number | undefined {
+	return value !== null && value !== undefined && Number.isInteger(value) && value > 0 && value <= 2_147_483_647
+		? value
+		: undefined
+}
+
+function legacyArchiveId(value: number | null | undefined): number | undefined {
+	return value !== null && value !== undefined && Number.isInteger(value) && value >= 0 && value <= 0xffffffff
+		? value
+		: undefined
+}
+
 /** Whole-snapshot URL: `${host}/s/${snapshotId}`. */
 export function playgroundBase(snapshotId: string, host: string = DEFAULT_PLAYGROUND_HOST): string {
 	return `${normalizeHost(host)}/s/${encodeURIComponent(snapshotId)}`
@@ -51,26 +65,46 @@ export function resolvePlaygroundHost(metaPlayground: string | null | undefined,
 }
 
 /**
- * Deep link auditing a single snippet:
- * - `statejson` with a source id → `?id=<stateJsonSourceId>` (opens the JSON evidence object).
- * - `markdown`/`appendix` with a node id → `/playground#focus=<nodeIds[0]>` (highlights the block).
- * - otherwise → the whole-snapshot base URL.
+ * Deep link auditing a single snippet by its canonical public Evidence ID.
  */
+export function citationUrl(snapshotId: string, location: CitationLocation | null | undefined, host?: string): string
+/** @deprecated Pass the location as the second argument; source is no longer needed. */
 export function citationUrl(
 	snapshotId: string,
 	source: CitationSource,
 	location: CitationLocation | null | undefined,
-	host: string = DEFAULT_PLAYGROUND_HOST,
+	host?: string,
+): string
+export function citationUrl(
+	snapshotId: string,
+	sourceOrLocation: CitationSource | CitationLocation | null | undefined,
+	locationOrHost?: CitationLocation | string | null,
+	legacyHost: string = DEFAULT_PLAYGROUND_HOST,
 ): string {
+	const legacySignature = typeof sourceOrLocation === 'string'
+	const source = legacySignature ? sourceOrLocation : undefined
+	const location = legacySignature
+		? typeof locationOrHost === 'string'
+			? undefined
+			: locationOrHost
+		: sourceOrLocation
+	const host = legacySignature
+		? legacyHost
+		: typeof locationOrHost === 'string'
+			? locationOrHost
+			: DEFAULT_PLAYGROUND_HOST
 	const base = playgroundBase(snapshotId, host)
-	return Match.value(source).pipe(
-		Match.when('statejson', () => {
-			const sourceId = location?.stateJsonSourceId
-			return sourceId != null ? `${base}?id=${sourceId}` : base
-		}),
-		Match.orElse(() => {
-			const nodeId = location?.nodeIds?.[0]
-			return nodeId != null ? `${base}/playground#focus=${nodeId}` : base
-		}),
-	)
+	const evidenceId = publicEvidenceId(location?.evidenceId)
+	if (evidenceId !== undefined) {
+		return `${base}?id=${evidenceId}`
+	}
+	if (source === 'statejson') {
+		const legacyId = legacyArchiveId(location?.stateJsonSourceId)
+		return legacyId === undefined ? base : `${base}?id=${legacyId}`
+	}
+	if (source === 'markdown' || source === 'appendix') {
+		const nodeId = legacyArchiveId(location?.nodeIds?.[0])
+		return nodeId === undefined ? base : `${base}/playground#focus=${nodeId}`
+	}
+	return base
 }