@expandai/sdk 0.18.0 → 0.19.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@expandai/sdk",
 	"type": "module",
-	"version": "0.18.0",
+	"version": "0.19.0",
 	"private": false,
 	"description": "TypeScript SDK for ExpandAI",
 	"author": "ExpandAI",
@@ -44,7 +44,8 @@
 		"./*": {
 			"types": "./build/dts/*.d.ts",
 			"import": "./build/esm/*.js"
-		}
+		},
+		"./internal/*": "./src/*.ts"
 	},
 	"scripts": {
 		"generate": "tsx scripts/generate-client.ts",

package/src/FetchJson.ts

@@ -14,29 +14,22 @@ import { decodeError, unexpectedStatus } from './HttpClientHelpers.js'
 
 /** Search snippet with the extracted `json` value preserved (statejson snippets only). */
 export const FetchSearchSnippetWithJson = S.Struct({
-	type: S.optionalWith(S.Literal('text'), { nullable: true, default: () => 'text' as const }),
-	source: S.Literal('markdown', 'appendix', 'statejson'),
-	text: S.String,
+	...Generated.FetchSearchResult.fields.snippets.value.fields,
 	json: S.optionalWith(S.Unknown, { nullable: true }),
-	score: S.Number.pipe(S.greaterThanOrEqualTo(0), S.lessThanOrEqualTo(1)),
-	location: S.optionalWith(Generated.FetchSearchSnippetLocation, { nullable: true }),
 })
 
 export const FetchSearchResultWithJson = S.Struct({
-	query: S.String,
+	...Generated.FetchSearchResult.fields,
 	snippets: S.Array(FetchSearchSnippetWithJson),
-	meta: S.optionalWith(Generated.FetchSearchMeta, { nullable: true }),
 })
 
 export class FetchObjectModeResultWithJson extends S.Class<FetchObjectModeResultWithJson>(
 	'FetchObjectModeResultWithJson',
 )({
-	meta: Generated.FetchObjectModeMeta,
-	markdown: S.String,
-	json: S.Array(Generated.FetchObjectModeEvidence),
+	...Generated.FetchObjectModeResult.fields,
 	data: S.optionalWith(
 		S.Struct({
-			assets: S.optionalWith(S.Array(Generated.FetchAssetReference), { nullable: true }),
+			...Generated.FetchObjectModeResult.fields.data.from.fields,
 			search: S.optionalWith(FetchSearchResultWithJson, { nullable: true }),
 		}),
 		{ nullable: true },
@@ -75,7 +68,10 @@ export const fetchObjectModeJson = (
 					'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),
 				}),
 			),

package/src/Generated.ts

@@ -186,6 +186,16 @@ export class InternalError extends S.Class<InternalError>('InternalError')({
 	_tag: InternalErrorTag,
 }) {}
 
+export class FetchNavigationFailedFailureType extends S.Literal('browserInternalDocument') {}
+
+export class FetchNavigationFailedTag extends S.Literal('FetchNavigationFailed') {}
+
+export class FetchNavigationFailed extends S.Class<FetchNavigationFailed>('FetchNavigationFailed')({
+	url: S.String,
+	failureType: FetchNavigationFailedFailureType,
+	_tag: FetchNavigationFailedTag,
+}) {}
+
 export class ServiceUnavailableTag extends S.Literal('ServiceUnavailable') {}
 
 export class ServiceUnavailable extends S.Class<ServiceUnavailable>('ServiceUnavailable')({
@@ -194,6 +204,22 @@ export class ServiceUnavailable extends S.Class<ServiceUnavailable>('ServiceUnav
 	_tag: ServiceUnavailableTag,
 }) {}
 
+export class FetchCaptureTimeoutTag extends S.Literal('FetchCaptureTimeout') {}
+
+export class FetchCaptureTimeout extends S.Class<FetchCaptureTimeout>('FetchCaptureTimeout')({
+	url: S.String,
+	timeoutMs: S.optionalWith(S.Number, { nullable: true }),
+	_tag: FetchCaptureTimeoutTag,
+}) {}
+
+export class FetchCapacityTimeoutTag extends S.Literal('FetchCapacityTimeout') {}
+
+export class FetchCapacityTimeout extends S.Class<FetchCapacityTimeout>('FetchCapacityTimeout')({
+	url: S.String,
+	timeoutMs: S.optionalWith(S.Number, { nullable: true }),
+	_tag: FetchCapacityTimeoutTag,
+}) {}
+
 export class FetchFetchJsonParams extends S.Struct({
 	include: S.optionalWith(S.String, { nullable: true }),
 }) {}
@@ -276,7 +302,7 @@ export class FetchObjectModeStateJsonHint extends S.Struct({
 
 export class FetchObjectModeMarkdownHint extends S.Struct({
 	url: S.String,
-	moreTokens: S.Number,
+	moreTokens: S.optionalWith(S.Number, { nullable: true }),
 }) {}
 
 export class FetchObjectModeMeta extends S.Struct({
@@ -319,6 +345,10 @@ export class FetchObjectModeEvidenceRole extends S.Literal(
 	'other',
 ) {}
 
+export class FetchObjectModeEvidenceUrlRedacted extends S.Literal(true) {}
+
+export class FetchObjectModeEvidenceUrlOmitted extends S.Literal('invalid', 'unsafe', 'too-long') {}
+
 export class FetchObjectModeEvidence extends S.Struct({
 	id: S.Number,
 	kind: FetchObjectModeEvidenceKind,
@@ -328,6 +358,8 @@ export class FetchObjectModeEvidence extends S.Struct({
 	method: S.optionalWith(S.String, { nullable: true }),
 	moreTokens: S.optionalWith(S.Number, { nullable: true }),
 	keys: S.optionalWith(S.Array(S.String), { nullable: true }),
+	urlRedacted: S.optionalWith(FetchObjectModeEvidenceUrlRedacted, { nullable: true }),
+	urlOmitted: S.optionalWith(FetchObjectModeEvidenceUrlOmitted, { nullable: true }),
 }) {}
 
 export class FetchAssetReferenceKind extends S.Literal('data-url') {}
@@ -342,6 +374,20 @@ export class FetchAssetReference extends S.Struct({
 	bytes: S.Number,
 }) {}
 
+export class FetchDegradedInfoReason extends S.Literal('pageTooLarge', 'modelInputTooLarge') {}
+
+export class FetchDegradedInfoLimitKind extends S.Literal('domsnapshot_bytes', 'ast_bytes', 'hfc_tokens') {}
+
+export class FetchDegradedInfo extends S.Struct({
+	reason: FetchDegradedInfoReason,
+	skipped: S.Array(S.Literal('hfc')),
+	limitKind: FetchDegradedInfoLimitKind,
+	measuredBytes: S.optionalWith(S.Int.pipe(S.greaterThanOrEqualTo(0)), { nullable: true }),
+	thresholdBytes: S.optionalWith(S.Int.pipe(S.greaterThanOrEqualTo(0)), { nullable: true }),
+	measuredTokens: S.optionalWith(S.Int.pipe(S.greaterThanOrEqualTo(0)), { nullable: true }),
+	thresholdTokens: S.optionalWith(S.Int.pipe(S.greaterThanOrEqualTo(0)), { nullable: true }),
+}) {}
+
 export class Int extends S.Int {}
 
 export class FetchSearchSnippetLocation extends S.Struct({
@@ -354,7 +400,7 @@ export class FetchSearchSnippetLocation extends S.Struct({
 
 export class FetchSearchSourceMetaSource extends S.Literal('markdown', 'appendix', 'statejson') {}
 
-export class FetchSearchSourceMetaRanker extends S.Literal('zeroentropy', 'local_lexical') {}
+export class FetchSearchSourceMetaRanker extends S.Literal('zeroentropy', 'mixedbread', 'local_lexical') {}
 
 export class FetchSearchSourceMetaFallbackReason extends S.Literal('timeout', 'error') {}
 
@@ -394,6 +440,7 @@ export class FetchObjectModeResult extends S.Class<FetchObjectModeResult>('Fetch
 	data: S.optionalWith(
 		S.Struct({
 			assets: S.optionalWith(S.Array(FetchAssetReference), { nullable: true }),
+			degraded: S.optionalWith(FetchDegradedInfo, { nullable: true }),
 			search: S.optionalWith(FetchSearchResult, { nullable: true }),
 			screenshot: S.optionalWith(
 				S.Struct({
@@ -692,10 +739,14 @@ export class BatchedFetchItem extends S.Struct({
 			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 }),
+			degraded: S.optionalWith(FetchDegradedInfo, { nullable: true }),
 		}),
 		{ nullable: true },
 	),
-	error: S.optionalWith(S.Union(FetchBlocked, FetchPageTooLarge), { nullable: true }),
+	error: S.optionalWith(
+		S.Union(FetchBlocked, FetchPageTooLarge, FetchNavigationFailed, FetchCaptureTimeout, FetchCapacityTimeout),
+		{ nullable: true },
+	),
 }) {}
 
 export class PaginationMeta extends S.Struct({
@@ -782,7 +833,10 @@ export const make = (
 								'413': (r) => decodeError(r, FetchFetch413),
 								'429': (r) => decodeError(r, TooManyRequests),
 								'500': (r) => decodeError(r, InternalError),
+								'502': (r) => decodeError(r, FetchNavigationFailed),
 								'503': (r) => decodeError(r, ServiceUnavailable),
+								'504': (r) => decodeError(r, FetchCaptureTimeout),
+								'529': (r) => decodeError(r, FetchCapacityTimeout),
 								orElse: (response) => unexpectedStatus(request, response),
 							}),
 						),
@@ -805,7 +859,10 @@ export const make = (
 								'413': (r) => decodeError(r, FetchFetchJson413),
 								'429': (r) => decodeError(r, TooManyRequests),
 								'500': (r) => decodeError(r, InternalError),
+								'502': (r) => decodeError(r, FetchNavigationFailed),
 								'503': (r) => decodeError(r, ServiceUnavailable),
+								'504': (r) => decodeError(r, FetchCaptureTimeout),
+								'529': (r) => decodeError(r, FetchCapacityTimeout),
 								orElse: (response) => unexpectedStatus(request, response),
 							}),
 						),
@@ -924,7 +981,10 @@ export interface Client {
 		| typeof FetchFetch413.Type
 		| typeof TooManyRequests.Type
 		| typeof InternalError.Type
+		| typeof FetchNavigationFailed.Type
 		| typeof ServiceUnavailable.Type
+		| typeof FetchCaptureTimeout.Type
+		| typeof FetchCapacityTimeout.Type
 	>
 	readonly fetchFetchJson: (options: {
 		readonly params: typeof FetchFetchJsonParams.Encoded
@@ -939,7 +999,10 @@ export interface Client {
 		| typeof FetchFetchJson413.Type
 		| typeof TooManyRequests.Type
 		| typeof InternalError.Type
+		| typeof FetchNavigationFailed.Type
 		| typeof ServiceUnavailable.Type
+		| typeof FetchCaptureTimeout.Type
+		| typeof FetchCapacityTimeout.Type
 	>
 	readonly fetchFetchSearch: (
 		options: typeof FetchFetchSearchRequest.Encoded,

package/src/Internal.ts

@@ -27,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
@@ -57,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 }),
@@ -109,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 }),
@@ -118,13 +122,23 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 			(error) => apiError(500, error),
 		),
 		Match.when(
-			(error: unknown) => error instanceof Generated.ServiceUnavailable,
-			(error) => apiError(503, 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 }),
@@ -158,6 +172,19 @@ 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

package/src/Service.ts

@@ -83,6 +83,21 @@ 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
@@ -163,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),
 						}),
 					),
@@ -238,9 +256,30 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 						),
 				}),
 			)
+			// 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,
+				payload: { ...params, ...overrides },
 			}
 			return yield* withRetries(generated.fetchBatched(generatedRequest), retryOptions)
 		})