@expandai/sdk 0.17.1 → 0.18.0

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,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,