@expandai/sdk 0.19.0 → 0.20.0

package/src/EnvProxyHttpClient.ts

@@ -0,0 +1,71 @@
+import type { HttpClient } from '@effect/platform'
+import { NodeHttpClient, Undici } from '@effect/platform-node'
+import { Effect, Layer, Option } from 'effect'
+import { ExpandSdkError } from './Error.js'
+
+// Undici resolves each protocol's proxy as `lowercase ?? UPPERCASE` — the
+// lowercase variant wins even when empty, and an empty effective value means
+// "no proxy". `NO_PROXY` never fails to parse, so it is not checked.
+const PROXY_ENV_SOURCES: ReadonlyArray<readonly [string, string]> = [
+	['http_proxy', 'HTTP_PROXY'],
+	['https_proxy', 'HTTPS_PROXY'],
+]
+
+/**
+ * Describes the first configured proxy environment variable whose value is not
+ * a valid URL, or `None` when the proxy configuration is usable. Undici's
+ * `EnvHttpProxyAgent` throws a raw `TypeError: Invalid URL` mid-construction
+ * on such a value; callers surface this message early instead (the SDK's
+ * `buildServiceConfig`, the CLI's startup preflight). Checked with the same
+ * effective-value precedence undici applies, so a value undici would never
+ * parse is never rejected here.
+ */
+export function invalidProxyEnvMessage(): Option.Option<string> {
+	for (const [lowercase, uppercase] of PROXY_ENV_SOURCES) {
+		const name = process.env[lowercase] !== undefined ? lowercase : uppercase
+		const value = process.env[name]
+		if (value === undefined || value === '') {
+			continue
+		}
+		try {
+			new URL(value)
+		} catch {
+			// Mirrors undici: any value `new URL` rejects would crash EnvHttpProxyAgent.
+			return Option.some(
+				`Invalid proxy URL in the ${name} environment variable: ${JSON.stringify(value)}. Fix or unset it.`,
+			)
+		}
+	}
+	return Option.none()
+}
+
+/**
+ * `HttpClient` layer honoring the standard proxy environment variables
+ * `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (upper- or lowercase).
+ *
+ * Requests dispatch through undici's `EnvHttpProxyAgent`, which resolves the
+ * proxy configuration at acquisition and degrades to a plain undici `Agent`
+ * when no proxy variable is set.
+ *
+ * A malformed proxy URL dies with a descriptive `ExpandSdkError` rather than
+ * failing typed: an error channel here would ripple through every dependent
+ * service's `Default` layer type, and the callers that can act on the problem
+ * already validate eagerly via {@link invalidProxyEnvMessage}. The die is the
+ * safety net for paths that skip that, e.g. the CLI's exported MCP server.
+ */
+export const layer: Layer.Layer<HttpClient.HttpClient> = NodeHttpClient.layerUndiciWithoutDispatcher.pipe(
+	Layer.provide(
+		Layer.scoped(
+			NodeHttpClient.Dispatcher,
+			Effect.acquireRelease(
+				Effect.suspend(() =>
+					Option.match(invalidProxyEnvMessage(), {
+						onSome: (message) => Effect.die(new ExpandSdkError({ message })),
+						onNone: () => Effect.sync(() => new Undici.EnvHttpProxyAgent()),
+					}),
+				),
+				(dispatcher) => Effect.promise(() => dispatcher.destroy()),
+			),
+		),
+	),
+)

package/src/FetchJson.ts

@@ -2,7 +2,7 @@
 //
 // The OpenAPI spec declares `json` on each search snippet (the extracted State JSON value), but
 // the code generator drops the bare `unknown`-typed field, so `Generated.FetchObjectModeResult`
-// / `Generated.FetchSnapshotSearchResult` decode it away. These hand-written schemas re-add
+// / `Generated.FetchSnapshotHighlightsResult` decode it away. These hand-written schemas re-add
 // `json`, and the request functions mirror the generated client but decode the 200 body with
 // them — so callers that need to surface the cited JSON get it. Kept out of `Generated.ts` so the
 // OpenAPI conformance test (which checks the generated schemas) is unaffected.
@@ -10,38 +10,69 @@
 import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
 import { Effect, Schema as S } from 'effect'
 import * as Generated from './Generated.js'
-import { decodeError, unexpectedStatus } from './HttpClientHelpers.js'
+import { decodeError, decodeSuccess, unexpectedStatus } from './HttpClientHelpers.js'
 
 /** Search snippet with the extracted `json` value preserved (statejson snippets only). */
-export const FetchSearchSnippetWithJson = S.Struct({
-	...Generated.FetchSearchResult.fields.snippets.value.fields,
+export const FetchHighlightsSnippetWithJson = S.Struct({
+	...Generated.FetchHighlightsResult.fields.snippets.value.fields,
 	json: S.optionalWith(S.Unknown, { nullable: true }),
 })
 
-export const FetchSearchResultWithJson = S.Struct({
-	...Generated.FetchSearchResult.fields,
-	snippets: S.Array(FetchSearchSnippetWithJson),
+export const FetchHighlightsResultWithJson = S.Struct({
+	...Generated.FetchHighlightsResult.fields,
+	snippets: S.Array(FetchHighlightsSnippetWithJson),
+})
+
+/** Object-mode evidence with the inline JSON payload preserved. */
+export const FetchObjectModeEvidenceWithJson = S.Struct({
+	...Generated.FetchObjectModeEvidence.fields,
+	body: S.optionalWith(S.Unknown, { nullable: true }),
 })
 
 export class FetchObjectModeResultWithJson extends S.Class<FetchObjectModeResultWithJson>(
 	'FetchObjectModeResultWithJson',
 )({
 	...Generated.FetchObjectModeResult.fields,
+	json: S.Array(FetchObjectModeEvidenceWithJson),
 	data: S.optionalWith(
 		S.Struct({
 			...Generated.FetchObjectModeResult.fields.data.from.fields,
-			search: S.optionalWith(FetchSearchResultWithJson, { nullable: true }),
+			highlights: S.optionalWith(FetchHighlightsResultWithJson, { nullable: true }),
 		}),
 		{ nullable: true },
 	),
+	originError: S.optionalWith(Generated.FetchHttpOriginError, { nullable: true }),
 }) {}
 
-export class FetchSnapshotSearchResultWithJson extends S.Class<FetchSnapshotSearchResultWithJson>(
-	'FetchSnapshotSearchResultWithJson',
+/**
+ * The 200 body of `/v1/fetch/json`. An origin that never answered has no
+ * content to return, so the endpoint reports its outcome as the whole body
+ * rather than as an HTTP error status — a non-2xx there would mean Expand
+ * failed, which it did not.
+ *
+ * Discriminate on `_tag`, which only `FetchOriginError` carries.
+ */
+export const FetchObjectModeJsonResponse = S.Union(
+	FetchObjectModeResultWithJson,
+	Generated.FetchNetworkOriginError,
+	Generated.FetchHttpOriginRefusal,
+)
+export type FetchObjectModeJsonResponse = typeof FetchObjectModeJsonResponse.Type
+
+/** The unreachable-origin member of `FetchObjectModeJsonResponse`, after narrowing with `isFetchOriginError`. */
+export type FetchOriginErrorResponse = Extract<FetchObjectModeJsonResponse, { readonly _tag: 'FetchOriginError' }>
+
+/** Narrows a `FetchObjectModeJsonResponse` to the unreachable-origin case — the only variant with a `_tag`. */
+export function isFetchOriginError(response: FetchObjectModeJsonResponse): response is FetchOriginErrorResponse {
+	return '_tag' in response && response._tag === 'FetchOriginError'
+}
+
+export class FetchSnapshotHighlightsResultWithJson extends S.Class<FetchSnapshotHighlightsResultWithJson>(
+	'FetchSnapshotHighlightsResultWithJson',
 )({
 	snapshotId: S.String.pipe(S.minLength(1)),
 	response: Generated.ResponseInfo,
-	search: FetchSearchResultWithJson,
+	highlights: FetchHighlightsResultWithJson,
 	durationMs: S.Number.pipe(S.greaterThanOrEqualTo(0)),
 	playground: S.String,
 }) {}
@@ -61,15 +92,21 @@ export const fetchObjectModeJson = (
 			Effect.flatMap(
 				httpClient.execute(request),
 				HttpClientResponse.matchStatus({
-					'200': (response) => HttpClientResponse.schemaBodyJson(FetchObjectModeResultWithJson)(response),
+					// `decodeSuccess`, not a raw schema decode: a 2xx body this SDK cannot read is
+					// deterministic skew, and retrying it re-runs a full capture per attempt.
+					'200': (response) => decodeSuccess(response, FetchObjectModeJsonResponse),
 					'400': (response) => decodeError(response, Generated.FetchFetchJson400),
 					'401': (response) => decodeError(response, Generated.AuthFailed),
 					'403': (response) => decodeError(response, Generated.FetchFetchJson403),
-					'413': (response) => decodeError(response, Generated.PayloadTooLarge),
-					'429': (response) => decodeError(response, Generated.TooManyRequests),
+					'404': (response) => decodeError(response, Generated.FetchOriginNotFound),
+					'410': (response) => decodeError(response, Generated.FetchOriginGone),
+					'413': (response) => decodeError(response, Generated.FetchFetchJson413),
+					'415': (response) => decodeError(response, Generated.FetchUnsupportedContentType),
+					'422': (response) => decodeError(response, Generated.FetchVideoUnavailable),
+					'429': (response) => decodeError(response, Generated.FetchFetchJson429),
 					'500': (response) => decodeError(response, Generated.InternalError),
-					'502': (response) => decodeError(response, Generated.FetchNavigationFailed),
-					'503': (response) => decodeError(response, Generated.ServiceUnavailable),
+					'502': (response) => decodeError(response, Generated.FetchFetchJson502),
+					'503': (response) => decodeError(response, Generated.FetchFetchJson503),
 					'504': (response) => decodeError(response, Generated.FetchCaptureTimeout),
 					'529': (response) => decodeError(response, Generated.FetchCapacityTimeout),
 					orElse: (response) => unexpectedStatus(request, response),
@@ -78,24 +115,25 @@ export const fetchObjectModeJson = (
 		),
 	)
 
-/** Mirrors `Generated.Client['fetchFetchSearch']` but decodes the 200 body with `json` preserved. */
-export const fetchSnapshotSearch = (
+/** Mirrors `Generated.Client['snapshotsHighlights']` but decodes the 200 body with `json` preserved. */
+export const fetchSnapshotHighlights = (
 	httpClient: HttpClient.HttpClient,
-	options: typeof Generated.FetchFetchSearchRequest.Encoded,
+	snapshotId: string,
+	options: typeof Generated.SnapshotHighlightsInput.Encoded,
 ) =>
-	HttpClientRequest.make('POST')('/v1/fetch/search').pipe(
+	HttpClientRequest.make('POST')(`/v1/snapshots/${encodeURIComponent(snapshotId)}/highlights`).pipe(
 		(request) => Effect.orDie(HttpClientRequest.bodyJson(request, options)),
 		Effect.flatMap((request) =>
 			Effect.flatMap(
 				httpClient.execute(request),
 				HttpClientResponse.matchStatus({
-					'200': (response) => HttpClientResponse.schemaBodyJson(FetchSnapshotSearchResultWithJson)(response),
-					'400': (response) => decodeError(response, Generated.FetchFetchSearch400),
+					'200': (response) => decodeSuccess(response, FetchSnapshotHighlightsResultWithJson),
+					'400': (response) => decodeError(response, Generated.SnapshotsHighlights400),
 					'401': (response) => decodeError(response, Generated.AuthFailed),
-					'403': (response) => decodeError(response, Generated.FetchFetchSearch403),
-					'404': (response) => decodeError(response, Generated.FetchSnapshotSearchNotFound),
+					'403': (response) => decodeError(response, Generated.SnapshotsHighlights403),
+					'404': (response) => decodeError(response, Generated.FetchSnapshotHighlightsNotFound),
 					'413': (response) => decodeError(response, Generated.PayloadTooLarge),
-					'429': (response) => decodeError(response, Generated.TooManyRequests),
+					'429': (response) => decodeError(response, Generated.SnapshotsHighlights429),
 					'500': (response) => decodeError(response, Generated.InternalError),
 					'503': (response) => decodeError(response, Generated.ServiceUnavailable),
 					orElse: (response) => unexpectedStatus(request, response),