@expandai/sdk 0.16.0 → 0.17.1

package/src/HttpClientHelpers.ts

@@ -0,0 +1,24 @@
+import { HttpClientError, HttpClientRequest, HttpClientResponse } from '@effect/platform'
+import { Effect, Schema } from 'effect'
+
+export function unexpectedStatus(
+	request: HttpClientRequest.HttpClientRequest,
+	response: HttpClientResponse.HttpClientResponse,
+) {
+	return Effect.flatMap(
+		Effect.orElseSucceed(response.text, () => 'Unexpected status code'),
+		(description) =>
+			Effect.fail(
+				new HttpClientError.ResponseError({
+					request,
+					response,
+					reason: 'StatusCode',
+					description,
+				}),
+			),
+	)
+}
+
+export function decodeError<A, I, R>(response: HttpClientResponse.HttpClientResponse, schema: Schema.Schema<A, I, R>) {
+	return Effect.flatMap(HttpClientResponse.schemaBodyJson(schema)(response), Effect.fail)
+}

package/src/Internal.ts

@@ -0,0 +1,246 @@
+import { HttpClientError } from '@effect/platform'
+import { Cause, Effect, HashSet, Layer, Match, Option, ParseResult } from 'effect'
+import {
+	ExpandApiError,
+	ExpandClientError,
+	ExpandConnectionError,
+	type ExpandError,
+	ExpandSdkError,
+	ExpandTimeoutError,
+} from './Error.js'
+import * as Generated from './Generated.js'
+import {
+	type BatchedParams,
+	type BatchedResponse,
+	ExpandService,
+	type ExpandServiceOptions,
+	type FetchJsonParams,
+	type FetchJsonResponse,
+	type FetchParams,
+	type FetchResponse,
+	type FetchSearchParams,
+	type FetchSearchResponse,
+	type GetBatchedParams,
+	type GetBatchedResponse,
+	type RequestOptions,
+} from './Service.js'
+
+const RETRYABLE_STATUS_CODES = HashSet.make(408, 409, 429, 500, 502, 503, 504)
+
+interface TaggedApiError {
+	readonly _tag: string
+}
+
+function hasApiErrorTag(error: unknown, tag: string): error is TaggedApiError {
+	return typeof error === 'object' && error !== null && '_tag' in error && error._tag === tag
+}
+
+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}`
+	return new ExpandApiError({ message, status, body: error, cause: error })
+}
+
+/**
+ * Lift a raw failure (HTTP error, parse error, codegen-typed error class, or unrelated throwable)
+ * into the typed `ExpandError` union surfaced by the SDK. Used by `ExpandService` to construct
+ * its public error channel.
+ */
+export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
+	return 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 }),
+		),
+		Match.when(
+			(error: unknown) => error instanceof HttpClientError.RequestError,
+			(error) => new ExpandConnectionError({ message: error.message, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => error instanceof HttpClientError.ResponseError,
+			(error) =>
+				new ExpandApiError({
+					message: error.message,
+					status: error.response.status,
+					body: error.description,
+					cause: error,
+				}),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.AuthFailed,
+			(error) => new ExpandApiError({ message: 'AuthFailed', status: 401, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'AuthFailed'),
+			(error) => apiError(401, error),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'AccessBlocked'),
+			(error) => apiError(403, error),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.PayloadTooLarge,
+			(error) => new ExpandApiError({ message: 'PayloadTooLarge', status: 413, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'PayloadTooLarge'),
+			(error) => apiError(413, error),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.TooManyRequests,
+			(error) => new ExpandApiError({ message: 'TooManyRequests', status: 429, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'TooManyRequests'),
+			(error) => apiError(429, error),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.InternalError,
+			(error) => new ExpandApiError({ message: 'InternalError', status: 500, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'InternalError'),
+			(error) => apiError(500, error),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.ServiceUnavailable,
+			(error) => new ExpandApiError({ message: 'ServiceUnavailable', status: 503, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'ServiceUnavailable'),
+			(error) => apiError(503, error),
+		),
+		Match.when(
+			(error: unknown) => error instanceof Generated.HttpApiDecodeError,
+			(error) => new ExpandApiError({ message: 'HttpApiDecodeError', status: 400, body: error, cause: error }),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'HttpApiDecodeError') || hasApiErrorTag(error, 'BadRequest'),
+			(error) => apiError(400, error),
+		),
+		Match.when(
+			(error: unknown) => hasApiErrorTag(error, 'FetchSnapshotSearchNotFound'),
+			(error) => apiError(404, error),
+		),
+		// A response we couldn't decode (e.g. a 5xx whose body is empty or doesn't match the declared
+		// error schema) arrives as a bare ParseError with no status. Surface a clear SDK error instead
+		// of dumping the raw schema-mismatch tree as the message.
+		Match.when(
+			(error: unknown) => ParseResult.isParseError(error),
+			(error) => new ExpandSdkError({ message: 'Failed to decode the API response', cause: error }),
+		),
+		Match.orElse(
+			(error) => new ExpandSdkError({ message: error instanceof Error ? error.message : String(error), cause: error }),
+		),
+	)
+}
+
+/**
+ * Decide whether a failure should trigger a retry. Timeouts and connection errors are always
+ * retryable; API errors are retryable only for the standard transient status codes (408/409/429/5xx).
+ */
+export function isRetryable(error: unknown, timeoutMs: number): boolean {
+	// 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
+	// operations that retry (fetch/getBatched) are idempotent and safe to repeat.
+	if (ParseResult.isParseError(error)) {
+		return true
+	}
+	const expandError = toExpandError(error, timeoutMs)
+	return Match.value(expandError).pipe(
+		Match.when(
+			(error: unknown) => error instanceof ExpandTimeoutError,
+			() => true,
+		),
+		Match.when(
+			(error: unknown) => error instanceof ExpandConnectionError,
+			() => true,
+		),
+		Match.when(
+			(error: unknown) => error instanceof ExpandApiError,
+			(error) => HashSet.has(RETRYABLE_STATUS_CODES, error.status),
+		),
+		Match.orElse(() => false),
+	)
+}
+
+/**
+ * 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`
+ * 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.
+ */
+export class InternalClient extends Effect.Service<InternalClient>()('@expandai/sdk/InternalClient', {
+	effect: Effect.gen(function* () {
+		const service = yield* ExpandService
+
+		const fetch = (
+			params: FetchParams,
+			options: RequestOptions = {},
+		): Effect.Effect<FetchResponse, ExpandClientError> =>
+			service.fetch(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		const fetchJson = (
+			params: FetchJsonParams,
+			options: RequestOptions = {},
+		): Effect.Effect<FetchJsonResponse, ExpandClientError> =>
+			service.fetchJson(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		const fetchSearch = (
+			params: FetchSearchParams,
+			options: RequestOptions = {},
+		): Effect.Effect<FetchSearchResponse, ExpandClientError> =>
+			service.fetchSearch(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		const batched = (
+			params: BatchedParams,
+			options: RequestOptions = {},
+		): Effect.Effect<BatchedResponse, ExpandClientError> =>
+			service.batched(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		const getBatched = (
+			id: string,
+			options: GetBatchedParams & RequestOptions = {},
+		): Effect.Effect<GetBatchedResponse, ExpandClientError> =>
+			service.getBatched(id, options).pipe(Effect.mapError((error) => error.toPublicError()))
+
+		return { fetch, fetchJson, fetchSearch, batched, getBatched } as const
+	}),
+}) {
+	/**
+	 * Build a Layer providing `InternalClient` (and its `ExpandService` dependency) from the given
+	 * options. The layer can fail at acquisition with `ExpandSdkError` (propagated from
+	 * `ExpandService.layer`'s validation); callers running this for a Promise wrapper should pipe
+	 * through `translateCause`, which converts via `toPublicError` to the public `ExpandClientError`.
+	 */
+	static layer(options: ExpandServiceOptions = {}): Layer.Layer<InternalClient, ExpandSdkError> {
+		return this.Default.pipe(Layer.provide(ExpandService.layer(options)))
+	}
+
+	/**
+	 * Flatten an Effect failure cause into the value to throw from a Promise wrapper. Typed errors
+	 * (`ExpandClientError`, `ExpandSdkError`) pass through `toPublicError` if available; non-failure
+	 * causes (defects, interruption) get wrapped in a generic `ExpandClientError`.
+	 */
+	static translateCause(cause: Cause.Cause<unknown>): unknown {
+		const failure = Cause.failureOption(cause).pipe(Option.orElse(() => Cause.dieOption(cause)))
+		return Option.match(failure, {
+			onSome: (error) => (InternalClient.hasPublicErrorTranslator(error) ? error.toPublicError() : error),
+			onNone: () => new ExpandClientError(Cause.isInterrupted(cause) ? 'Request was interrupted' : Cause.pretty(cause)),
+		})
+	}
+
+	private static hasPublicErrorTranslator(error: unknown): error is { toPublicError: () => ExpandClientError } {
+		return (
+			typeof error === 'object' &&
+			error !== null &&
+			'toPublicError' in error &&
+			typeof error.toPublicError === 'function'
+		)
+	}
+}

package/src/Playground.ts

@@ -0,0 +1,76 @@
+// Public playground (expand.land) URL builders for citing fetch snapshots.
+//
+// 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
+//
+// A citation maps a search snippet (`source` + `location`) to the view that audits it.
+
+import { Match } from 'effect'
+
+export const DEFAULT_PLAYGROUND_HOST = 'https://expand.land'
+
+export type CitationSource = 'markdown' | 'appendix' | 'statejson'
+
+/** Snippet location subset needed to build a deep link. Tolerates `null` and `undefined`. */
+export interface CitationLocation {
+	readonly nodeIds?: ReadonlyArray<number> | null
+	readonly stateJsonSourceId?: number | null
+}
+
+function normalizeHost(host: string): string {
+	return host.replace(/\/+$/, '')
+}
+
+/** Whole-snapshot URL: `${host}/s/${snapshotId}`. */
+export function playgroundBase(snapshotId: string, host: string = DEFAULT_PLAYGROUND_HOST): string {
+	return `${normalizeHost(host)}/s/${encodeURIComponent(snapshotId)}`
+}
+
+/** Origin of a server-provided `meta.playground` URL, for reuse as the host (staging-safe). */
+export function playgroundOrigin(metaPlayground: string): string {
+	return new URL(metaPlayground).origin
+}
+
+/**
+ * Host to build citation links against: the origin of a server-provided `meta.playground`
+ * (authoritative, staging-safe) when present and parseable, else the caller's fallback.
+ */
+export function resolvePlaygroundHost(metaPlayground: string | null | undefined, fallback: string): string {
+	if (metaPlayground == null) {
+		return fallback
+	}
+	try {
+		return playgroundOrigin(metaPlayground)
+	} catch {
+		// meta.playground should always be a valid URL; guard defensively against a malformed value.
+		return fallback
+	}
+}
+
+/**
+ * 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.
+ */
+export function citationUrl(
+	snapshotId: string,
+	source: CitationSource,
+	location: CitationLocation | null | undefined,
+	host: string = DEFAULT_PLAYGROUND_HOST,
+): string {
+	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
+		}),
+	)
+}

package/src/Service.ts

@@ -0,0 +1,264 @@
+import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
+import { NodeHttpClient } from '@effect/platform-node'
+import { Context, Duration, Effect, flow, Layer, Schedule, Schema } from 'effect'
+import { ExpandSdkError } from './Error.js'
+import {
+	type FetchObjectModeResultWithJson,
+	type FetchSnapshotSearchResultWithJson,
+	fetchObjectModeJson,
+	fetchSnapshotSearch,
+} from './FetchJson.js'
+import * as Generated from './Generated.js'
+import { decodeError, unexpectedStatus } from './HttpClientHelpers.js'
+import { isRetryable, toExpandError } from './Internal.js'
+
+const DEFAULT_BASE_URL = 'https://api.expand.ai'
+const DEFAULT_TIMEOUT_MS = 60_000
+const DEFAULT_MAX_RETRIES = 2
+
+/**
+ * Options accepted by `ExpandService.layer`. All fields are optional; defaults match `ExpandClient`.
+ */
+export class ExpandServiceOptions extends Schema.Class<ExpandServiceOptions>('ExpandServiceOptions')(
+	{
+		/** API key. Falls back to the `EXPAND_API_KEY` environment variable. */
+		apiKey: Schema.optional(Schema.String).annotations({
+			description: 'API key. Falls back to the `EXPAND_API_KEY` environment variable.',
+		}),
+		/** API base URL. Defaults to `https://api.expand.ai`. */
+		baseUrl: Schema.optional(Schema.String).annotations({
+			description: 'API base URL. Defaults to `https://api.expand.ai`.',
+		}),
+		/**
+		 * Total wall-clock budget in milliseconds for the operation, including retries and backoff.
+		 * Each attempt gets `timeoutMs / (maxRetries + 1)`. 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.',
+		}),
+		/**
+		 * 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.
+		 */
+		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.',
+		}),
+	},
+	{ description: 'Options for constructing an `ExpandService` layer or `ExpandClient` instance.' },
+) {}
+
+/**
+ * Per-request overrides accepted by `ExpandService.fetch`/`batched`/`getBatched` (and, transitively,
+ * by `ExpandClient`'s methods).
+ */
+export class RequestOptions extends Schema.Class<RequestOptions>('RequestOptions')(
+	{
+		/** Override the configured `timeoutMs` for this request. Total wall-clock budget across all attempts. */
+		timeoutMs: Schema.optional(Schema.Number).annotations({
+			description: 'Override the configured `timeoutMs` for this request. Total wall-clock budget across all attempts.',
+		}),
+		/** Override the configured `maxRetries` for this request. */
+		maxRetries: Schema.optional(Schema.Number).annotations({
+			description: 'Override the configured `maxRetries` for this request.',
+		}),
+	},
+	{ description: 'Per-request overrides for an `ExpandService` operation.' },
+) {}
+
+export type FetchParams = typeof Generated.FetchFetchRequest.Encoded
+export type FetchResponse = string
+export type FetchRequestOptions = RequestOptions & typeof Generated.FetchFetchParams.Encoded
+export type FetchJsonParams = typeof Generated.FetchFetchJsonRequest.Encoded
+// `*WithJson` rather than the generated result: the codegen drops the statejson snippet `json`, so
+// the service decodes the body with the recovering schemas (see `FetchJson.ts`).
+export type FetchJsonResponse = FetchObjectModeResultWithJson
+export type FetchJsonRequestOptions = RequestOptions & typeof Generated.FetchFetchJsonParams.Encoded
+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 type GetBatchedParams = typeof Generated.FetchGetBatchedParams.Encoded
+export type GetBatchedResponse = typeof Generated.BatchedStatus.Type
+
+class ServiceConfig extends Schema.Class<ServiceConfig>('ExpandServiceConfig')({
+	apiKey: Schema.NonEmptyString,
+	baseUrl: Schema.NonEmptyString,
+	timeoutMs: Schema.Number,
+	maxRetries: Schema.Number,
+}) {}
+
+class ServiceConfigTag extends Context.Tag('@expandai/sdk/ExpandServiceConfig')<
+	ServiceConfigTag,
+	typeof ServiceConfig.Type
+>() {}
+
+/**
+ * Validate user-supplied options into a fully-defaulted `ServiceConfig`. Reads
+ * `EXPAND_API_KEY` from `process.env` when `options.apiKey` is missing. Used by
+ * `ExpandService.layer` (Effect-typed Layer error channel) and by `ExpandClient`
+ * (eagerly via `Effect.runSync` to preserve sync-throw constructor semantics).
+ */
+export const buildServiceConfig = Effect.fn('buildServiceConfig')(function* (options: ExpandServiceOptions) {
+	const apiKey = options.apiKey ?? process.env.EXPAND_API_KEY
+	if (!apiKey) {
+		return yield* new ExpandSdkError({ message: 'Missing Expand API key. Pass apiKey or set EXPAND_API_KEY.' })
+	}
+	return yield* Schema.decode(ServiceConfig)({
+		apiKey,
+		baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+	}).pipe(Effect.mapError((error) => new ExpandSdkError({ message: 'Invalid Expand client options', cause: error })))
+})
+
+/**
+ * Effect-native client for the Expand API. Mirrors the {@link ExpandClient} Promise interface —
+ * methods accept the same `RequestOptions` per-call overrides and return Effects with the typed
+ * `ExpandError` channel (`ExpandApiError | ExpandConnectionError | ExpandTimeoutError | ExpandSdkError`).
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const expand = yield* ExpandService
+ *   return yield* expand.fetch({ url: 'https://example.com' })
+ * }).pipe(Effect.provide(ExpandService.layer({ apiKey: 'sk_...' })))
+ * ```
+ */
+export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sdk/ExpandService', {
+	dependencies: [NodeHttpClient.layer],
+	effect: Effect.gen(function* () {
+		const config = yield* ServiceConfigTag
+		const httpClient = yield* HttpClient.HttpClient
+		const authedClient = httpClient.pipe(
+			HttpClient.mapRequest(
+				flow(
+					HttpClientRequest.prependUrl(config.baseUrl),
+					HttpClientRequest.setHeader('x-expand-api-key', config.apiKey),
+				),
+			),
+		)
+		const generated = Generated.make(authedClient)
+		const fetchMarkdown = (params: FetchParams, queryParams: typeof Generated.FetchFetchParams.Encoded = {}) =>
+			HttpClientRequest.make('POST')('/v1/fetch').pipe(
+				// Coalesce null -> undefined: the generated `include` schema is nullable, but `setUrlParams`
+				// throws on a null value. `undefined` is correctly dropped (no query param emitted).
+				HttpClientRequest.setUrlParams({ include: queryParams.include ?? undefined }),
+				(req) => Effect.orDie(HttpClientRequest.bodyJson(req, params)),
+				Effect.flatMap((request) =>
+					Effect.flatMap(
+						authedClient.execute(request),
+						HttpClientResponse.matchStatus({
+							'200': (response) => response.text,
+							'400': (response) => decodeError(response, Generated.FetchFetch400),
+							'401': (response) => decodeError(response, Generated.AuthFailed),
+							'403': (response) => decodeError(response, Generated.FetchFetch403),
+							'413': (response) => decodeError(response, Generated.PayloadTooLarge),
+							'429': (response) => decodeError(response, Generated.TooManyRequests),
+							'500': (response) => decodeError(response, Generated.InternalError),
+							'503': (response) => decodeError(response, Generated.ServiceUnavailable),
+							orElse: (response) => unexpectedStatus(request, response),
+						}),
+					),
+				),
+			)
+
+		// Generic over the operation's success/error/requirement channels so callers (fetch/batched/getBatched)
+		// retain their full Effect typing through the wrapper.
+		const withRetries = Effect.fn('ExpandService.withRetries')(function* <A, E, R>(
+			operation: Effect.Effect<A, E, R>,
+			requestOptions: RequestOptions = {},
+		) {
+			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)))
+			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)),
+			)
+		})
+
+		const fetch = Effect.fn('ExpandService.fetch')(function* (
+			params: FetchParams,
+			requestOptions: FetchRequestOptions = {},
+		) {
+			const { include, ...retryOptions } = requestOptions
+			return yield* withRetries(fetchMarkdown(params, { include }), retryOptions)
+		})
+
+		const fetchJson = Effect.fn('ExpandService.fetchJson')(function* (
+			params: FetchJsonParams,
+			requestOptions: FetchJsonRequestOptions = {},
+		) {
+			const { include, ...retryOptions } = requestOptions
+			// `fetchObjectModeJson` mirrors the generated call but preserves the statejson snippet `json`.
+			// Coalesce null -> undefined before `setUrlParams`, which throws on null.
+			return yield* withRetries(
+				fetchObjectModeJson(authedClient, { params: { include: include ?? undefined }, payload: params }),
+				retryOptions,
+			)
+		})
+
+		const fetchSearch = Effect.fn('ExpandService.fetchSearch')(function* (
+			params: FetchSearchParams,
+			requestOptions: RequestOptions = {},
+		) {
+			// `fetchSnapshotSearch` mirrors the generated call but preserves the statejson snippet `json`.
+			return yield* withRetries(fetchSnapshotSearch(authedClient, params), requestOptions)
+		})
+
+		const batched = Effect.fn('ExpandService.batched')(function* (
+			params: BatchedParams,
+			requestOptions: RequestOptions = {},
+		) {
+			// 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 getBatched = Effect.fn('ExpandService.getBatched')(function* (
+			id: string,
+			options: GetBatchedParams & RequestOptions = {},
+		) {
+			// Pull RequestOptions out, pass everything else through as query params. Drift-resilient: any
+			// new GetBatchedParams field added by codegen flows through `params` automatically.
+			const { timeoutMs, maxRetries, ...params } = options
+			return yield* withRetries(generated.fetchGetBatched(id, params), { timeoutMs, maxRetries })
+		})
+
+		return { fetch, fetchJson, fetchSearch, batched, getBatched } as const
+	}),
+}) {
+	/**
+	 * Build a Layer providing `ExpandService` with the given options. Validation (missing apiKey,
+	 * Schema-rejected config) surfaces via the Layer's error channel as `ExpandSdkError`.
+	 */
+	static layer(options: ExpandServiceOptions = {}) {
+		return Layer.unwrapEffect(
+			buildServiceConfig(options).pipe(
+				Effect.map((config) => ExpandService.Default.pipe(Layer.provide(Layer.succeed(ServiceConfigTag, config)))),
+			),
+		)
+	}
+}

package/src/index.ts

@@ -1,22 +1,28 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
-export { Expand as default } from './client';
-
-export { type Uploadable, toFile } from './core/uploads';
-export { APIPromise } from './core/api-promise';
-export { Expand, type ClientOptions } from './client';
+export type {
+	BatchedParams,
+	BatchedResponse,
+	ExpandClientOptions,
+	FetchJsonParams,
+	FetchJsonRequestOptions,
+	FetchJsonResponse,
+	FetchParams,
+	FetchRequestOptions,
+	FetchResponse,
+	FetchSearchParams,
+	FetchSearchResponse,
+	GetBatchedParams,
+	GetBatchedResponse,
+} from './Client.js'
+export { ExpandClient } from './Client.js'
+export type { ExpandError } from './Error.js'
 export {
-  ExpandError,
-  APIError,
-  APIConnectionError,
-  APIConnectionTimeoutError,
-  APIUserAbortError,
-  NotFoundError,
-  ConflictError,
-  RateLimitError,
-  BadRequestError,
-  AuthenticationError,
-  InternalServerError,
-  PermissionDeniedError,
-  UnprocessableEntityError,
-} from './core/error';
+	ExpandApiError,
+	ExpandClientApiError,
+	ExpandClientConnectionError,
+	ExpandClientError,
+	ExpandClientTimeoutError,
+	ExpandConnectionError,
+	ExpandSdkError,
+	ExpandTimeoutError,
+} from './Error.js'
+export { ExpandService, ExpandServiceOptions, RequestOptions } from './Service.js'