@expandai/sdk 0.17.0 → 0.17.1

package/package.json

@@ -1,137 +1,54 @@
 {
-  "name": "@expandai/sdk",
-  "version": "0.17.0",
-  "description": "The official TypeScript library for the Expand API",
-  "author": "Expand <support@expand.ai>",
-  "types": "./index.d.ts",
-  "main": "./index.js",
-  "type": "commonjs",
-  "repository": "github:expandai/expandai-node",
-  "license": "Apache-2.0",
-  "files": [
-    "**/*"
-  ],
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {},
-  "exports": {
-    ".": {
-      "require": {
-        "types": "./index.d.ts",
-        "default": "./index.js"
-      },
-      "types": "./index.d.mts",
-      "default": "./index.mjs"
-    },
-    "./api-promise": {
-      "import": "./api-promise.mjs",
-      "require": "./api-promise.js"
-    },
-    "./api-promise.js": {
-      "default": "./api-promise.js"
-    },
-    "./api-promise.mjs": {
-      "default": "./api-promise.mjs"
-    },
-    "./client": {
-      "import": "./client.mjs",
-      "require": "./client.js"
-    },
-    "./client.js": {
-      "default": "./client.js"
-    },
-    "./client.mjs": {
-      "default": "./client.mjs"
-    },
-    "./core/*.mjs": {
-      "default": "./core/*.mjs"
-    },
-    "./core/*.js": {
-      "default": "./core/*.js"
-    },
-    "./core/*": {
-      "import": "./core/*.mjs",
-      "require": "./core/*.js"
-    },
-    "./error": {
-      "import": "./error.mjs",
-      "require": "./error.js"
-    },
-    "./error.js": {
-      "default": "./error.js"
-    },
-    "./error.mjs": {
-      "default": "./error.mjs"
-    },
-    "./index": {
-      "import": "./index.mjs",
-      "require": "./index.js"
-    },
-    "./index.js": {
-      "default": "./index.js"
-    },
-    "./index.mjs": {
-      "default": "./index.mjs"
-    },
-    "./resource": {
-      "import": "./resource.mjs",
-      "require": "./resource.js"
-    },
-    "./resource.js": {
-      "default": "./resource.js"
-    },
-    "./resource.mjs": {
-      "default": "./resource.mjs"
-    },
-    "./resources/*.mjs": {
-      "default": "./resources/*.mjs"
-    },
-    "./resources/*.js": {
-      "default": "./resources/*.js"
-    },
-    "./resources/*": {
-      "import": "./resources/*.mjs",
-      "require": "./resources/*.js"
-    },
-    "./resources": {
-      "import": "./resources.mjs",
-      "require": "./resources.js"
-    },
-    "./resources.js": {
-      "default": "./resources.js"
-    },
-    "./resources.mjs": {
-      "default": "./resources.mjs"
-    },
-    "./uploads": {
-      "import": "./uploads.mjs",
-      "require": "./uploads.js"
-    },
-    "./uploads.js": {
-      "default": "./uploads.js"
-    },
-    "./uploads.mjs": {
-      "default": "./uploads.mjs"
-    },
-    "./version": {
-      "import": "./version.mjs",
-      "require": "./version.js"
-    },
-    "./version.js": {
-      "default": "./version.js"
-    },
-    "./version.mjs": {
-      "default": "./version.mjs"
-    }
-  },
-  "scripts": {
-    "test": "./scripts/test",
-    "build": "./scripts/build",
-    "format": "./scripts/format",
-    "tsn": "ts-node -r tsconfig-paths/register",
-    "lint": "./scripts/lint",
-    "fix": "./scripts/format"
-  }
-}
+	"name": "@expandai/sdk",
+	"type": "module",
+	"version": "0.17.1",
+	"private": false,
+	"description": "TypeScript SDK for ExpandAI",
+	"author": "ExpandAI",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/expandai/expandai-node.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"build/dts",
+		"build/esm",
+		"src",
+		"!**/*.tsbuildinfo"
+	],
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./build/dts/index.d.ts",
+			"import": "./build/esm/index.js"
+		},
+		"./*": "./src/*.ts"
+	},
+	"scripts": {
+		"generate": "tsx scripts/generate-client.ts",
+		"build": "tsc -b tsconfig.build.json",
+		"check": "tsc -b tsconfig.json",
+		"check:test": "tsc -b tsconfig.test.json",
+		"lint": "biome check --write --no-errors-on-unmatched",
+		"lint:check": "biome check",
+		"format": "biome format --write",
+		"format:check": "biome format",
+		"test": "vitest run --exclude 'test/**/*.integration.test.ts'",
+		"test:integration": "vitest run integration"
+	},
+	"dependencies": {
+		"@effect/platform": "0.96.1",
+		"@effect/platform-node": "0.106.0",
+		"effect": "3.21.2"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.14",
+		"@effect/vitest": "0.29.0",
+		"@tim-smart/openapi-gen": "0.3.12",
+		"@types/node": "^25.5.2",
+		"vitest": "4.1.4"
+	}
+}

package/src/Client.ts

@@ -0,0 +1,128 @@
+import { Effect, Either, Exit, Layer } from 'effect'
+import { InternalClient } from './Internal.js'
+import {
+	type BatchedParams,
+	type BatchedResponse,
+	buildServiceConfig,
+	type ExpandServiceOptions,
+	type FetchJsonParams,
+	type FetchJsonRequestOptions,
+	type FetchJsonResponse,
+	type FetchParams,
+	type FetchRequestOptions,
+	type FetchResponse,
+	type FetchSearchParams,
+	type FetchSearchResponse,
+	type GetBatchedParams,
+	type GetBatchedResponse,
+	type RequestOptions,
+} from './Service.js'
+
+export type {
+	BatchedParams,
+	BatchedResponse,
+	FetchJsonParams,
+	FetchJsonRequestOptions,
+	FetchJsonResponse,
+	FetchParams,
+	FetchRequestOptions,
+	FetchResponse,
+	FetchSearchParams,
+	FetchSearchResponse,
+	GetBatchedParams,
+	GetBatchedResponse,
+} from './Service.js'
+
+/** Options for constructing an {@link ExpandClient}. Same shape as `ExpandServiceOptions`. */
+export type ExpandClientOptions = ExpandServiceOptions
+
+/**
+ * Promise-based client for the Expand API. Holds an {@link InternalClient} layer and runs Effects
+ * against it, translating typed failures into the `ExpandClient*Error` hierarchy that async/await
+ * consumers expect.
+ *
+ * @example
+ * ```ts
+ * const client = new ExpandClient({ apiKey: 'sk_...' })
+ * const result = await client.fetch({ url: 'https://example.com' })
+ * ```
+ */
+export class ExpandClient {
+	private readonly layer: Layer.Layer<InternalClient>
+
+	constructor(options: ExpandClientOptions = {}) {
+		// Eagerly validate so the Promise constructor matches the documented sync-throw contract.
+		// `buildServiceConfig` is a pure-sync Effect (env-var read + Schema.decode), so runSync is safe.
+		const result = Effect.runSync(buildServiceConfig(options).pipe(Effect.either))
+		if (Either.isLeft(result)) {
+			throw result.left.toPublicError()
+		}
+		// Validation passed; the layer's acquisition Effect re-runs the same logic, so it cannot fail.
+		// Layer.orDie narrows the error channel to `never` while keeping a die fallback as a defensive
+		// net (translateCause picks up dies via Cause.dieOption and converts via toPublicError).
+		this.layer = InternalClient.layer(options).pipe(Layer.orDie)
+	}
+
+	/**
+	 * Fetch a URL through the Expand API.
+	 *
+	 * @throws {ExpandClientApiError} on 4xx/5xx responses
+	 * @throws {ExpandClientTimeoutError} when the request exceeds `timeoutMs`
+	 * @throws {ExpandClientConnectionError} on network failures
+	 * @throws {ExpandClientError} for any other failure
+	 */
+	async fetch(params: FetchParams, options: FetchRequestOptions = {}): Promise<FetchResponse> {
+		return this.run((client) => client.fetch(params, options))
+	}
+
+	/**
+	 * Fetch a URL through the object-mode endpoint.
+	 *
+	 * Returns `{ meta, markdown, json }`; use {@link fetch} for the raw markdown document.
+	 */
+	async fetchJson(params: FetchJsonParams, options: FetchJsonRequestOptions = {}): Promise<FetchJsonResponse> {
+		return this.run((client) => client.fetchJson(params, options))
+	}
+
+	/**
+	 * Search a previous Fetch response by `snapshotId` without starting a new capture.
+	 */
+	async fetchSearch(params: FetchSearchParams, options: RequestOptions = {}): Promise<FetchSearchResponse> {
+		return this.run((client) => client.fetchSearch(params, options))
+	}
+
+	/**
+	 * Kick off an asynchronous batched fetch over one or more URLs. Returns a batched-run ID that can
+	 * be polled via {@link getBatched}.
+	 *
+	 * Retries are disabled by default. Pass `{ maxRetries: N }` to opt in.
+	 *
+	 * @throws {ExpandClientApiError} on 4xx/5xx responses
+	 * @throws {ExpandClientTimeoutError} when the request exceeds `timeoutMs`
+	 * @throws {ExpandClientConnectionError} on network failures
+	 * @throws {ExpandClientError} for any other failure
+	 */
+	async batched(params: BatchedParams, options: RequestOptions = {}): Promise<BatchedResponse> {
+		return this.run((client) => client.batched(params, options))
+	}
+
+	/**
+	 * Fetch the status and accumulated results for a batched run previously started by {@link batched}.
+	 *
+	 * @throws {ExpandClientApiError} on 4xx/5xx responses
+	 * @throws {ExpandClientTimeoutError} when the request exceeds `timeoutMs`
+	 * @throws {ExpandClientConnectionError} on network failures
+	 * @throws {ExpandClientError} for any other failure
+	 */
+	async getBatched(id: string, options: GetBatchedParams & RequestOptions = {}): Promise<GetBatchedResponse> {
+		return this.run((client) => client.getBatched(id, options))
+	}
+
+	private async run<A>(body: (ic: InternalClient) => Effect.Effect<A, Error>): Promise<A> {
+		const exit = await Effect.runPromiseExit(InternalClient.use(body).pipe(Effect.provide(this.layer)))
+		if (Exit.isSuccess(exit)) {
+			return exit.value
+		}
+		throw InternalClient.translateCause(exit.cause)
+	}
+}

package/src/Error.ts

@@ -0,0 +1,105 @@
+import { Schema } from 'effect'
+
+/**
+ * Effect-side base error. Schema.TaggedError; Effect consumers receive these in the error channel.
+ */
+export class ExpandSdkError extends Schema.TaggedError<ExpandSdkError>()('ExpandSdkError', {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect),
+}) {
+	toPublicError() {
+		return new ExpandClientError(this.message, { cause: this.cause })
+	}
+}
+
+/**
+ * Effect-side error for non-2xx API responses. Inspect `status` and `body` for details.
+ */
+export class ExpandApiError extends Schema.TaggedError<ExpandApiError>()('ExpandApiError', {
+	message: Schema.String,
+	status: Schema.Number,
+	body: Schema.optional(Schema.Unknown),
+	cause: Schema.optional(Schema.Defect),
+}) {
+	toPublicError() {
+		return new ExpandClientApiError(this.message, { status: this.status, body: this.body, cause: this.cause })
+	}
+}
+
+/**
+ * Effect-side error when the SDK cannot reach the API (DNS, connection refused, socket reset, etc.).
+ */
+export class ExpandConnectionError extends Schema.TaggedError<ExpandConnectionError>()('ExpandConnectionError', {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect),
+}) {
+	toPublicError() {
+		return new ExpandClientConnectionError(this.message, { cause: this.cause })
+	}
+}
+
+/**
+ * Effect-side error when a request exceeds its configured `timeoutMs`.
+ */
+export class ExpandTimeoutError extends Schema.TaggedError<ExpandTimeoutError>()('ExpandTimeoutError', {
+	message: Schema.String,
+	timeoutMs: Schema.Number,
+	cause: Schema.optional(Schema.Defect),
+}) {
+	toPublicError() {
+		return new ExpandClientTimeoutError(this.message, { timeoutMs: this.timeoutMs, cause: this.cause })
+	}
+}
+
+/**
+ * Union of every error the Effect-side `ExpandService` can fail with.
+ */
+export type ExpandError = ExpandSdkError | ExpandApiError | ExpandConnectionError | ExpandTimeoutError
+
+/**
+ * Promise-side base class. Catch this to handle any failure thrown by `ExpandClient`.
+ */
+export class ExpandClientError extends Error {
+	constructor(message: string, options: ErrorOptions = {}) {
+		super(message, options)
+		this.name = 'ExpandClientError'
+	}
+}
+
+/**
+ * Promise-side error for non-2xx API responses. Inspect `status` and `body` for details.
+ */
+export class ExpandClientApiError extends ExpandClientError {
+	readonly status: number
+	readonly body: unknown
+
+	constructor(message: string, options: ErrorOptions & { readonly status: number; readonly body?: unknown }) {
+		super(message, options)
+		this.name = 'ExpandClientApiError'
+		this.status = options.status
+		this.body = options.body
+	}
+}
+
+/**
+ * Promise-side error when the SDK cannot reach the API (DNS, connection refused, socket reset, etc.).
+ */
+export class ExpandClientConnectionError extends ExpandClientError {
+	constructor(message: string, options: ErrorOptions = {}) {
+		super(message, options)
+		this.name = 'ExpandClientConnectionError'
+	}
+}
+
+/**
+ * Promise-side error when a request exceeds its configured `timeoutMs`.
+ */
+export class ExpandClientTimeoutError extends ExpandClientConnectionError {
+	readonly timeoutMs: number
+
+	constructor(message: string, options: ErrorOptions & { readonly timeoutMs: number }) {
+		super(message, options)
+		this.name = 'ExpandClientTimeoutError'
+		this.timeoutMs = options.timeoutMs
+	}
+}

package/src/FetchJson.ts

@@ -0,0 +1,109 @@
+// `json`-recovering decode for the fetch JSON-mode and snapshot-search endpoints.
+//
+// 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
+// `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.
+
+import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
+import * as Generated from '@expandai/sdk/Generated'
+import { decodeError, unexpectedStatus } from '@expandai/sdk/HttpClientHelpers'
+import { Effect, Schema as S } from 'effect'
+
+/** 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,
+	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,
+	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),
+	data: S.optionalWith(
+		S.Struct({
+			assets: S.optionalWith(S.Array(Generated.FetchAssetReference), { nullable: true }),
+			captureTelemetry: S.optionalWith(Generated.CaptureTelemetryInfo, { nullable: true }),
+			search: S.optionalWith(FetchSearchResultWithJson, { nullable: true }),
+		}),
+		{ nullable: true },
+	),
+}) {}
+
+export class FetchSnapshotSearchResultWithJson extends S.Class<FetchSnapshotSearchResultWithJson>(
+	'FetchSnapshotSearchResultWithJson',
+)({
+	snapshotId: S.String.pipe(S.minLength(1)),
+	response: Generated.ResponseInfo,
+	search: FetchSearchResultWithJson,
+	durationMs: S.Number.pipe(S.greaterThanOrEqualTo(0)),
+}) {}
+
+/** Mirrors `Generated.Client['fetchFetchJson']` but decodes the 200 body with `json` preserved. */
+export const fetchObjectModeJson = (
+	httpClient: HttpClient.HttpClient,
+	options: {
+		readonly params: typeof Generated.FetchFetchJsonParams.Encoded
+		readonly payload: typeof Generated.FetchFetchJsonRequest.Encoded
+	},
+) =>
+	HttpClientRequest.make('POST')('/v1/fetch/json').pipe(
+		HttpClientRequest.setUrlParams(options.params.include !== undefined ? { include: options.params.include } : {}),
+		(request) => Effect.orDie(HttpClientRequest.bodyJson(request, options.payload)),
+		Effect.flatMap((request) =>
+			Effect.flatMap(
+				httpClient.execute(request),
+				HttpClientResponse.matchStatus({
+					'200': (response) => HttpClientResponse.schemaBodyJson(FetchObjectModeResultWithJson)(response),
+					'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),
+					'500': (response) => decodeError(response, Generated.InternalError),
+					'503': (response) => decodeError(response, Generated.ServiceUnavailable),
+					orElse: (response) => unexpectedStatus(request, response),
+				}),
+			),
+		),
+	)
+
+/** Mirrors `Generated.Client['fetchFetchSearch']` but decodes the 200 body with `json` preserved. */
+export const fetchSnapshotSearch = (
+	httpClient: HttpClient.HttpClient,
+	options: typeof Generated.FetchFetchSearchRequest.Encoded,
+) =>
+	HttpClientRequest.make('POST')('/v1/fetch/search').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),
+					'401': (response) => decodeError(response, Generated.AuthFailed),
+					'403': (response) => decodeError(response, Generated.FetchFetchSearch403),
+					'404': (response) => decodeError(response, Generated.FetchSnapshotSearchNotFound),
+					'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),
+				}),
+			),
+		),
+	)