@expandai/sdk 0.17.2 → 0.19.0

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,
@@ -25,7 +27,7 @@ import {
 	type RequestOptions,
 } from './Service.js'
 
-const RETRYABLE_STATUS_CODES = HashSet.make(408, 409, 429, 500, 502, 503, 504)
+const RETRYABLE_STATUS_CODES = HashSet.make(408, 409, 429, 500, 502, 503, 504, 529)
 
 interface TaggedApiError {
 	readonly _tag: string
@@ -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 })
 }
 
@@ -49,7 +57,9 @@ function apiError(status: number, error: unknown): ExpandApiError {
  * its public error channel.
  */
 export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
-	return Match.value(error).pipe(
+	// Split across two `pipe` calls: the arm list is longer than `pipe`'s 20-argument overloads.
+	// Arms are evaluated top to bottom across both halves, so the ordering is unaffected.
+	const transportAndClientErrors = Match.value(error).pipe(
 		Match.when(
 			(error: unknown) => error instanceof Cause.TimeoutException,
 			(error) => new ExpandTimeoutError({ message: `Request timed out after ${timeoutMs}ms`, timeoutMs, cause: error }),
@@ -80,6 +90,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 }),
@@ -96,6 +111,8 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 			(error: unknown) => hasApiErrorTag(error, 'TooManyRequests'),
 			(error) => apiError(429, error),
 		),
+	)
+	return transportAndClientErrors.pipe(
 		Match.when(
 			(error: unknown) => error instanceof Generated.InternalError,
 			(error) => new ExpandApiError({ message: 'InternalError', status: 500, body: error, cause: error }),
@@ -105,13 +122,23 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 			(error) => apiError(500, error),
 		),
 		Match.when(
-			(error: unknown) => error instanceof Generated.ServiceUnavailable,
-			(error) => new ExpandApiError({ message: 'ServiceUnavailable', status: 503, body: error, cause: error }),
+			(error: unknown) => hasApiErrorTag(error, 'FetchNavigationFailed'),
+			(error) => apiError(502, error),
 		),
+		// No `instanceof Generated.ServiceUnavailable` arm: decoded instances carry `_tag`, so the
+		// tag predicate already matches them and both would produce the same `apiError(503, ...)`.
 		Match.when(
 			(error: unknown) => hasApiErrorTag(error, 'ServiceUnavailable'),
 			(error) => apiError(503, error),
 		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'FetchCaptureTimeout'),
+			(error) => apiError(504, error),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'FetchCapacityTimeout'),
+			(error) => apiError(529, error),
+		),
 		Match.when(
 			(error: unknown) => error instanceof Generated.HttpApiDecodeError,
 			(error) => new ExpandApiError({ message: 'HttpApiDecodeError', status: 400, body: error, cause: error }),
@@ -142,6 +169,22 @@ 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
+	}
+	// A 502 FetchNavigationFailed is a deterministic verdict about the target page (the browser
+	// committed an internal error document), not a transient gateway failure — retrying re-runs a
+	// full capture for the same outcome.
+	if (hasApiErrorTag(error, 'FetchNavigationFailed')) {
+		return false
+	}
+	// A typed 504 FetchCaptureTimeout is the conservative fallback when no result was publishable by
+	// the request deadline and queue-only expiry was not proven. Automatic retry remains disabled so
+	// ambiguous timeouts do not amplify a control-plane incident. A deliberate retry may still be
+	// appropriate; a bare intermediary 504 stays on the normal retryable-status path.
+	if (hasApiErrorTag(error, 'FetchCaptureTimeout')) {
+		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 +213,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 +242,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 +252,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
 }

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,27 @@ 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
+	/**
+	 * Body fields the public contract does not declare, merged verbatim into the
+	 * request payload.
+	 *
+	 * The API accepts a small number of options that are deliberately absent from
+	 * the published OpenAPI document and refused for any organization not on the
+	 * server's internal allowlist. Because the generated request schema is built
+	 * from that same public document, it drops undeclared keys on encode — so an
+	 * internal caller passing one through `params` would get a request that looks
+	 * correct and carries nothing. This is the supported way to send one.
+	 *
+	 * Not for application code: anything here is unversioned, unvalidated by the
+	 * SDK, and rejected by the API unless the calling organization is allowlisted.
+	 */
+	readonly internalOverrides?: Readonly<Record<string, unknown>>
+}
 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,
@@ -160,7 +178,10 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 							'413': (response) => decodeError(response, Generated.PayloadTooLarge),
 							'429': (response) => decodeError(response, Generated.TooManyRequests),
 							'500': (response) => decodeError(response, Generated.InternalError),
+							'502': (response) => decodeError(response, Generated.FetchNavigationFailed),
 							'503': (response) => decodeError(response, Generated.ServiceUnavailable),
+							'504': (response) => decodeError(response, Generated.FetchCaptureTimeout),
+							'529': (response) => decodeError(response, Generated.FetchCapacityTimeout),
 							orElse: (response) => unexpectedStatus(request, response),
 						}),
 					),
@@ -175,20 +196,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 +241,47 @@ 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)}`,
+							),
+						),
+				}),
+			)
+			// Merged after the generated payload because the generated schema drops any
+			// key it does not declare — silently, which is the dangerous part. See
+			// `BatchedRequestOptions.internalOverrides` for why it is not declared.
+			//
+			// A collision is refused rather than resolved: this hatch exists to add
+			// undeclared fields, and letting it win over `urls` or `include` would
+			// mean a request could quietly fetch something other than what the caller
+			// passed.
+			const overrides = requestOptions.internalOverrides ?? {}
+			// Checked against the schema's declared fields, not against the keys this
+			// particular call happened to set: an omitted-but-declared field like
+			// `include` could otherwise be supplied here and bypass the generated
+			// contract entirely.
+			const collisions = Object.keys(overrides).filter((key) =>
+				Object.hasOwn(Generated.FetchBatchedRequest.fields, key),
+			)
+			if (collisions.length > 0) {
+				return yield* new ExpandSdkError({
+					message: `internalOverrides may not replace declared request fields: ${collisions.join(', ')}`,
+				})
+			}
+			const generatedRequest: Parameters<typeof generated.fetchBatched>[0] = {
+				params: { 'x-idempotency-key': idempotencyKey },
+				payload: { ...params, ...overrides },
+			}
+			return yield* withRetries(generated.fetchBatched(generatedRequest), retryOptions)
 		})
 
 		const getBatched = Effect.fn('ExpandService.getBatched')(function* (
@@ -247,7 +294,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,