@effect-uai/exa 0.9.0 → 0.10.0

package/dist/ExaContents.d.mts

@@ -0,0 +1,48 @@
+import { ExaLivecrawl } from "./models.mjs";
+import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import * as AiError from "@effect-uai/core/AiError";
+import { CommonReadRequest, ReadResponse, WebRead } from "@effect-uai/core/WebRead";
+
+//#region src/ExaContents.d.ts
+declare namespace ExaContents_d_exports {
+  export { Config, ExaContents, ExaContentsRequest, ExaContentsService, layer, make };
+}
+/**
+ * Exa-typed read request. Widens {@link CommonReadRequest} with Exa
+ * `/contents` knobs; the common fields map onto Exa's wire body (see the
+ * codec below).
+ */
+type ExaContentsRequest = CommonReadRequest & {
+  /** Freshness / cache policy - see {@link ExaLivecrawl}. */readonly livecrawl?: ExaLivecrawl; /** Cap on the returned content length (Exa `text.maxCharacters`). */
+  readonly maxCharacters?: number;
+};
+type ExaContentsService = {
+  readonly read: (request: ExaContentsRequest) => Effect.Effect<ReadResponse, AiError.AiError>;
+};
+declare const ExaContents_base: Context.ServiceClass<ExaContents, "@betalyra/effect-uai/providers/exa/ExaContents", ExaContentsService>;
+/**
+ * Provider-typed service tag. Yield this for Exa-typed reads (its own
+ * `/contents` knobs); yield the generic `WebRead` tag for provider-portable
+ * code. Both are registered by {@link layer}.
+ */
+declare class ExaContents extends ExaContents_base {}
+type Config = {
+  readonly apiKey: Redacted.Redacted;
+  readonly baseUrl?: string;
+};
+/**
+ * Build an `ExaContentsService` value. For Layer-based setup, prefer
+ * {@link layer}.
+ */
+declare const make: (cfg: Config) => Effect.Effect<ExaContentsService, never, HttpClient.HttpClient>;
+/**
+ * Layer registering both the provider-typed `ExaContents` tag and the generic
+ * `WebRead` tag over one implementation. A `CommonReadRequest` is structurally
+ * an `ExaContentsRequest` with the extra knobs unset, so the generic
+ * registration forwards directly.
+ */
+declare const layer: (cfg: Config) => Layer.Layer<ExaContents | WebRead, never, HttpClient.HttpClient>;
+//#endregion
+export { Config, ExaContents, ExaContentsRequest, ExaContentsService, layer, make, ExaContents_d_exports as t };
+//# sourceMappingURL=ExaContents.d.mts.map

package/dist/ExaContents.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExaContents.d.mts","names":[],"sources":["../src/ExaContents.ts"],"mappings":";;;;;;;;;;;;;;;KAoBY,kBAAA,GAAqB,iBAAA;sEAEtB,SAAA,GAAY,YAAA;WAEZ,aAAA;AAAA;AAAA,KAGC,kBAAA;EAAA,SACD,IAAA,GAAO,OAAA,EAAS,kBAAA,KAAuB,MAAA,CAAO,MAAA,CAAO,YAAA,EAAc,OAAA,CAAQ,OAAA;AAAA;AAAA,cACrF,gBAAA;;;;;;cAOY,WAAA,SAAoB,gBAAA;AAAA,KAIrB,MAAA;EAAA,SACD,MAAA,EAAQ,QAAA,CAAS,QAAA;EAAA,SACjB,OAAA;AAAA;;;;;cAsIE,IAAA,GACX,GAAA,EAAK,MAAA,KACJ,MAAA,CAAO,MAAA,CAAO,kBAAA,SAA2B,UAAA,CAAW,UAAA;;;;;;;cAY1C,KAAA,GACX,GAAA,EAAK,MAAA,KACJ,KAAA,CAAM,KAAA,CAAM,WAAA,GAAc,OAAA,SAAgB,UAAA,CAAW,UAAA"}

package/dist/ExaContents.mjs

@@ -0,0 +1,134 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { Context, Effect, Layer, Redacted, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import * as AiError from "@effect-uai/core/AiError";
+import { WebRead } from "@effect-uai/core/WebRead";
+//#region src/ExaContents.ts
+var ExaContents_exports = /* @__PURE__ */ __exportAll({
+	ExaContents: () => ExaContents,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* Provider-typed service tag. Yield this for Exa-typed reads (its own
+* `/contents` knobs); yield the generic `WebRead` tag for provider-portable
+* code. Both are registered by {@link layer}.
+*/
+var ExaContents = class extends Context.Service()("@betalyra/effect-uai/providers/exa/ExaContents") {};
+const buildBody = (request) => {
+	const text = {
+		...request.maxCharacters !== void 0 && { maxCharacters: request.maxCharacters },
+		...request.format === "html" && { includeHtmlTags: true }
+	};
+	return {
+		urls: [request.url],
+		text,
+		...request.livecrawl !== void 0 && { livecrawl: request.livecrawl }
+	};
+};
+const WireResult = Schema.Struct({
+	id: Schema.optional(Schema.String),
+	url: Schema.String,
+	title: Schema.optional(Schema.NullOr(Schema.String)),
+	text: Schema.optional(Schema.NullOr(Schema.String))
+});
+const WireStatus = Schema.Struct({
+	id: Schema.optional(Schema.String),
+	status: Schema.optional(Schema.String),
+	source: Schema.optional(Schema.String)
+});
+const WireResponse = Schema.Struct({
+	requestId: Schema.optional(Schema.String),
+	results: Schema.Array(WireResult),
+	statuses: Schema.optional(Schema.Array(WireStatus))
+});
+const toResponse = (wire, result) => {
+	const title = result.title ?? void 0;
+	return {
+		url: result.url,
+		content: result.text ?? "",
+		...title !== void 0 && { title },
+		raw: wire
+	};
+};
+const transportFailure = (cause) => new AiError.Unavailable({
+	provider: "exa",
+	raw: cause
+});
+const httpStatusError = (status, body) => {
+	const provider = "exa";
+	const raw = body;
+	if (status === 429) return new AiError.RateLimited({
+		provider,
+		raw
+	});
+	if (status === 408 || status === 504) return new AiError.Timeout({
+		provider,
+		raw
+	});
+	if (status === 401) return new AiError.AuthFailed({
+		provider,
+		subtype: "auth",
+		raw
+	});
+	if (status === 403) return new AiError.AuthFailed({
+		provider,
+		subtype: "permission",
+		raw
+	});
+	if (status === 402) return new AiError.AuthFailed({
+		provider,
+		subtype: "billing",
+		raw
+	});
+	if (status >= 500) return new AiError.Unavailable({
+		provider,
+		status,
+		raw
+	});
+	return new AiError.InvalidRequest({
+		provider,
+		raw
+	});
+};
+const baseUrl = (cfg) => cfg.baseUrl ?? "https://api.exa.ai";
+const postContents = (cfg, body) => Effect.gen(function* () {
+	const client = yield* HttpClient.HttpClient;
+	const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/contents`).pipe(HttpClientRequest.setHeader("x-api-key", Redacted.value(cfg.apiKey)), HttpClientRequest.bodyJsonUnsafe(body));
+	const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure));
+	if (response.status >= 400) {
+		const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+		return yield* httpStatusError(response.status, text);
+	}
+	const json = yield* response.json.pipe(Effect.mapError(transportFailure));
+	return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(Effect.mapError(transportFailure));
+});
+const readImpl = (cfg) => (request) => Effect.gen(function* () {
+	const wire = yield* postContents(cfg, buildBody(request));
+	const result = wire.results[0];
+	if (result === void 0) return yield* new AiError.Unavailable({
+		provider: "exa",
+		raw: wire
+	});
+	return toResponse(wire, result);
+});
+/**
+* Build an `ExaContentsService` value. For Layer-based setup, prefer
+* {@link layer}.
+*/
+const make = (cfg) => Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({ read: (request) => readImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)) }));
+/**
+* Layer registering both the provider-typed `ExaContents` tag and the generic
+* `WebRead` tag over one implementation. A `CommonReadRequest` is structurally
+* an `ExaContentsRequest` with the extra knobs unset, so the generic
+* registration forwards directly.
+*/
+const layer = (cfg) => {
+	const typed = Layer.effect(ExaContents, make(cfg));
+	const generic = Layer.effect(WebRead, Effect.map(make(cfg), (s) => ({ read: (request) => s.read(request) })));
+	return Layer.merge(typed, generic);
+};
+//#endregion
+export { ExaContents, layer, make, ExaContents_exports as t };
+
+//# sourceMappingURL=ExaContents.mjs.map

package/dist/ExaContents.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExaContents.mjs","names":[],"sources":["../src/ExaContents.ts"],"sourcesContent":["import { Context, Effect, Layer, Redacted, Schema } from \"effect\"\nimport { HttpClient, HttpClientRequest } from \"effect/unstable/http\"\nimport * as AiError from \"@effect-uai/core/AiError\"\nimport {\n  type CommonReadRequest,\n  type ReadResponse,\n  WebRead,\n  type WebReadService,\n} from \"@effect-uai/core/WebRead\"\nimport type { ExaLivecrawl } from \"./models.js\"\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Exa-typed read request. Widens {@link CommonReadRequest} with Exa\n * `/contents` knobs; the common fields map onto Exa's wire body (see the\n * codec below).\n */\nexport type ExaContentsRequest = CommonReadRequest & {\n  /** Freshness / cache policy - see {@link ExaLivecrawl}. */\n  readonly livecrawl?: ExaLivecrawl\n  /** Cap on the returned content length (Exa `text.maxCharacters`). */\n  readonly maxCharacters?: number\n}\n\nexport type ExaContentsService = {\n  readonly read: (request: ExaContentsRequest) => Effect.Effect<ReadResponse, AiError.AiError>\n}\n\n/**\n * Provider-typed service tag. Yield this for Exa-typed reads (its own\n * `/contents` knobs); yield the generic `WebRead` tag for provider-portable\n * code. Both are registered by {@link layer}.\n */\nexport class ExaContents extends Context.Service<ExaContents, ExaContentsService>()(\n  \"@betalyra/effect-uai/providers/exa/ExaContents\",\n) {}\n\nexport type Config = {\n  readonly apiKey: Redacted.Redacted\n  readonly baseUrl?: string\n}\n\n// ---------------------------------------------------------------------------\n// Codec - request body\n// ---------------------------------------------------------------------------\n\ntype WireText = {\n  readonly maxCharacters?: number\n  readonly includeHtmlTags?: boolean\n}\n\ntype WireBody = {\n  readonly urls: ReadonlyArray<string>\n  readonly text: WireText\n  readonly livecrawl?: string\n}\n\n// Exa returns markdown by default; `includeHtmlTags: true` returns HTML tags\n// instead. Both land on the single `text` field of the result.\nconst buildBody = (request: ExaContentsRequest): WireBody => {\n  const text: WireText = {\n    ...(request.maxCharacters !== undefined && { maxCharacters: request.maxCharacters }),\n    ...(request.format === \"html\" && { includeHtmlTags: true }),\n  }\n  return {\n    urls: [request.url],\n    text,\n    ...(request.livecrawl !== undefined && { livecrawl: request.livecrawl }),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Codec - response\n// ---------------------------------------------------------------------------\n\nconst WireResult = Schema.Struct({\n  id: Schema.optional(Schema.String),\n  url: Schema.String,\n  title: Schema.optional(Schema.NullOr(Schema.String)),\n  text: Schema.optional(Schema.NullOr(Schema.String)),\n})\ntype WireResult = typeof WireResult.Type\n\nconst WireStatus = Schema.Struct({\n  id: Schema.optional(Schema.String),\n  status: Schema.optional(Schema.String),\n  source: Schema.optional(Schema.String),\n})\n\nconst WireResponse = Schema.Struct({\n  requestId: Schema.optional(Schema.String),\n  results: Schema.Array(WireResult),\n  statuses: Schema.optional(Schema.Array(WireStatus)),\n})\ntype WireResponse = typeof WireResponse.Type\n\nconst toResponse = (wire: WireResponse, result: WireResult): ReadResponse => {\n  const title = result.title ?? undefined\n  return {\n    url: result.url,\n    content: result.text ?? \"\",\n    ...(title !== undefined && { title }),\n    raw: wire,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// HTTP\n// ---------------------------------------------------------------------------\n\nconst transportFailure = (cause: unknown): AiError.AiError =>\n  new AiError.Unavailable({ provider: \"exa\", raw: cause })\n\nconst httpStatusError = (status: number, body: string): AiError.AiError => {\n  const provider = \"exa\"\n  const raw = body\n  if (status === 429) return new AiError.RateLimited({ provider, raw })\n  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })\n  if (status === 401) return new AiError.AuthFailed({ provider, subtype: \"auth\", raw })\n  if (status === 403) return new AiError.AuthFailed({ provider, subtype: \"permission\", raw })\n  if (status === 402) return new AiError.AuthFailed({ provider, subtype: \"billing\", raw })\n  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })\n  return new AiError.InvalidRequest({ provider, raw })\n}\n\nconst baseUrl = (cfg: Config): string => cfg.baseUrl ?? \"https://api.exa.ai\"\n\nconst postContents = (\n  cfg: Config,\n  body: WireBody,\n): Effect.Effect<WireResponse, AiError.AiError, HttpClient.HttpClient> =>\n  Effect.gen(function* () {\n    const client = yield* HttpClient.HttpClient\n    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/contents`).pipe(\n      HttpClientRequest.setHeader(\"x-api-key\", Redacted.value(cfg.apiKey)),\n      HttpClientRequest.bodyJsonUnsafe(body),\n    )\n    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))\n    if (response.status >= 400) {\n      const text = yield* response.text.pipe(Effect.orElseSucceed(() => \"\"))\n      return yield* httpStatusError(response.status, text)\n    }\n    const json = yield* response.json.pipe(Effect.mapError(transportFailure))\n    return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(\n      Effect.mapError(transportFailure),\n    )\n  })\n\nconst readImpl =\n  (cfg: Config) =>\n  (\n    request: ExaContentsRequest,\n  ): Effect.Effect<ReadResponse, AiError.AiError, HttpClient.HttpClient> =>\n    Effect.gen(function* () {\n      const wire = yield* postContents(cfg, buildBody(request))\n      // Exa reports per-URL crawl failures in `results` / `statuses` rather\n      // than an HTTP error; a missing first result means the single URL could\n      // not be read.\n      const result = wire.results[0]\n      if (result === undefined) {\n        return yield* new AiError.Unavailable({ provider: \"exa\", raw: wire })\n      }\n      return toResponse(wire, result)\n    })\n\n// ---------------------------------------------------------------------------\n// Constructors\n// ---------------------------------------------------------------------------\n\n/**\n * Build an `ExaContentsService` value. For Layer-based setup, prefer\n * {@link layer}.\n */\nexport const make = (\n  cfg: Config,\n): Effect.Effect<ExaContentsService, never, HttpClient.HttpClient> =>\n  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({\n    read: (request) =>\n      readImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),\n  }))\n\n/**\n * Layer registering both the provider-typed `ExaContents` tag and the generic\n * `WebRead` tag over one implementation. A `CommonReadRequest` is structurally\n * an `ExaContentsRequest` with the extra knobs unset, so the generic\n * registration forwards directly.\n */\nexport const layer = (\n  cfg: Config,\n): Layer.Layer<ExaContents | WebRead, never, HttpClient.HttpClient> => {\n  const typed = Layer.effect(ExaContents, make(cfg))\n  const generic = Layer.effect(\n    WebRead,\n    Effect.map(make(cfg), (s): WebReadService => ({ read: (request) => s.read(request) })),\n  )\n  return Layer.merge(typed, generic)\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,3 +1,4 @@
-import { ExaCategory, ExaSearchType } from "./models.mjs";
+import { ExaCategory, ExaLivecrawl, ExaSearchType } from "./models.mjs";
+import { t as ExaContents_d_exports } from "./ExaContents.mjs";
 import { t as ExaSearch_d_exports } from "./ExaSearch.mjs";
-export { ExaCategory, ExaSearch_d_exports as ExaSearch, ExaSearchType };
+export { ExaCategory, ExaContents_d_exports as ExaContents, ExaLivecrawl, ExaSearch_d_exports as ExaSearch, ExaSearchType };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { t as ExaContents_exports } from "./ExaContents.mjs";
 import { t as ExaSearch_exports } from "./ExaSearch.mjs";
 import "./models.mjs";
-export { ExaSearch_exports as ExaSearch };
+export { ExaContents_exports as ExaContents, ExaSearch_exports as ExaSearch };

package/dist/models.d.mts

@@ -19,6 +19,12 @@ type ExaSearchType = "auto" | "fast" | "instant" | "deep-lite" | "deep" | "deep-
  * Provider-specific, so it lives on `ExaSearchRequest`.
  */
 type ExaCategory = "company" | "research paper" | "news" | "personal site" | "financial report" | "people" | (string & {});
+/**
+ * Exa `/contents` freshness knob. Controls whether the page is fetched live
+ * or served from Exa's cache. Provider-specific, so it lives on
+ * `ExaContentsRequest`.
+ */
+type ExaLivecrawl = "never" | "fallback" | "preferred" | "always" | (string & {});
 //#endregion
-export { ExaCategory, ExaSearchType };
+export { ExaCategory, ExaLivecrawl, ExaSearchType };
 //# sourceMappingURL=models.d.mts.map

package/dist/models.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.mts","names":[],"sources":["../src/models.ts"],"mappings":";;AAcA;;;;;AAgBA;;;;;;;;KAhBY,aAAA;;;;;KAgBA,WAAA"}
+{"version":3,"file":"models.d.mts","names":[],"sources":["../src/models.ts"],"mappings":";;AAcA;;;;;AAgBA;;;;;AAeA;;;KA/BY,aAAA;;;;;KAgBA,WAAA;;;;;;KAeA,YAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@effect-uai/exa",
-  "version": "0.9.0",
-  "description": "Exa provider for @effect-uai/core (web search).",
+  "version": "0.10.0",
+  "description": "Exa provider for @effect-uai/core (web search, web read).",
   "keywords": [
     "ai",
     "effect",
     "exa",
     "search",
+    "web-read",
     "web-search"
   ],
   "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/exa",
@@ -34,6 +35,10 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./ExaContents": {
+      "types": "./dist/ExaContents.d.mts",
+      "import": "./dist/ExaContents.mjs"
+    },
     "./ExaSearch": {
       "types": "./dist/ExaSearch.d.mts",
       "import": "./dist/ExaSearch.mjs"
@@ -45,7 +50,7 @@
   "devDependencies": {
     "effect": "4.0.0-beta.57",
     "typescript": "^6.0.3",
-    "@effect-uai/core": "0.9.0"
+    "@effect-uai/core": "0.10.0"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",

package/src/ExaContents.ts

@@ -0,0 +1,200 @@
+import { Context, Effect, Layer, Redacted, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import {
+  type CommonReadRequest,
+  type ReadResponse,
+  WebRead,
+  type WebReadService,
+} from "@effect-uai/core/WebRead"
+import type { ExaLivecrawl } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Exa-typed read request. Widens {@link CommonReadRequest} with Exa
+ * `/contents` knobs; the common fields map onto Exa's wire body (see the
+ * codec below).
+ */
+export type ExaContentsRequest = CommonReadRequest & {
+  /** Freshness / cache policy - see {@link ExaLivecrawl}. */
+  readonly livecrawl?: ExaLivecrawl
+  /** Cap on the returned content length (Exa `text.maxCharacters`). */
+  readonly maxCharacters?: number
+}
+
+export type ExaContentsService = {
+  readonly read: (request: ExaContentsRequest) => Effect.Effect<ReadResponse, AiError.AiError>
+}
+
+/**
+ * Provider-typed service tag. Yield this for Exa-typed reads (its own
+ * `/contents` knobs); yield the generic `WebRead` tag for provider-portable
+ * code. Both are registered by {@link layer}.
+ */
+export class ExaContents extends Context.Service<ExaContents, ExaContentsService>()(
+  "@betalyra/effect-uai/providers/exa/ExaContents",
+) {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Codec - request body
+// ---------------------------------------------------------------------------
+
+type WireText = {
+  readonly maxCharacters?: number
+  readonly includeHtmlTags?: boolean
+}
+
+type WireBody = {
+  readonly urls: ReadonlyArray<string>
+  readonly text: WireText
+  readonly livecrawl?: string
+}
+
+// Exa returns markdown by default; `includeHtmlTags: true` returns HTML tags
+// instead. Both land on the single `text` field of the result.
+const buildBody = (request: ExaContentsRequest): WireBody => {
+  const text: WireText = {
+    ...(request.maxCharacters !== undefined && { maxCharacters: request.maxCharacters }),
+    ...(request.format === "html" && { includeHtmlTags: true }),
+  }
+  return {
+    urls: [request.url],
+    text,
+    ...(request.livecrawl !== undefined && { livecrawl: request.livecrawl }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Codec - response
+// ---------------------------------------------------------------------------
+
+const WireResult = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  url: Schema.String,
+  title: Schema.optional(Schema.NullOr(Schema.String)),
+  text: Schema.optional(Schema.NullOr(Schema.String)),
+})
+type WireResult = typeof WireResult.Type
+
+const WireStatus = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.String),
+  source: Schema.optional(Schema.String),
+})
+
+const WireResponse = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  results: Schema.Array(WireResult),
+  statuses: Schema.optional(Schema.Array(WireStatus)),
+})
+type WireResponse = typeof WireResponse.Type
+
+const toResponse = (wire: WireResponse, result: WireResult): ReadResponse => {
+  const title = result.title ?? undefined
+  return {
+    url: result.url,
+    content: result.text ?? "",
+    ...(title !== undefined && { title }),
+    raw: wire,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "exa", raw: cause })
+
+const httpStatusError = (status: number, body: string): AiError.AiError => {
+  const provider = "exa"
+  const raw = body
+  if (status === 429) return new AiError.RateLimited({ provider, raw })
+  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })
+  if (status === 401) return new AiError.AuthFailed({ provider, subtype: "auth", raw })
+  if (status === 403) return new AiError.AuthFailed({ provider, subtype: "permission", raw })
+  if (status === 402) return new AiError.AuthFailed({ provider, subtype: "billing", raw })
+  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })
+  return new AiError.InvalidRequest({ provider, raw })
+}
+
+const baseUrl = (cfg: Config): string => cfg.baseUrl ?? "https://api.exa.ai"
+
+const postContents = (
+  cfg: Config,
+  body: WireBody,
+): Effect.Effect<WireResponse, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/contents`).pipe(
+      HttpClientRequest.setHeader("x-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(
+      Effect.mapError(transportFailure),
+    )
+  })
+
+const readImpl =
+  (cfg: Config) =>
+  (
+    request: ExaContentsRequest,
+  ): Effect.Effect<ReadResponse, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const wire = yield* postContents(cfg, buildBody(request))
+      // Exa reports per-URL crawl failures in `results` / `statuses` rather
+      // than an HTTP error; a missing first result means the single URL could
+      // not be read.
+      const result = wire.results[0]
+      if (result === undefined) {
+        return yield* new AiError.Unavailable({ provider: "exa", raw: wire })
+      }
+      return toResponse(wire, result)
+    })
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an `ExaContentsService` value. For Layer-based setup, prefer
+ * {@link layer}.
+ */
+export const make = (
+  cfg: Config,
+): Effect.Effect<ExaContentsService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    read: (request) =>
+      readImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+  }))
+
+/**
+ * Layer registering both the provider-typed `ExaContents` tag and the generic
+ * `WebRead` tag over one implementation. A `CommonReadRequest` is structurally
+ * an `ExaContentsRequest` with the extra knobs unset, so the generic
+ * registration forwards directly.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<ExaContents | WebRead, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(ExaContents, make(cfg))
+  const generic = Layer.effect(
+    WebRead,
+    Effect.map(make(cfg), (s): WebReadService => ({ read: (request) => s.read(request) })),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/index.ts

@@ -1,2 +1,3 @@
+export * as ExaContents from "./ExaContents.js"
 export * as ExaSearch from "./ExaSearch.js"
 export * from "./models.js"

package/src/models.ts

@@ -37,3 +37,16 @@ export type ExaCategory =
   | "people"
   // eslint-disable-next-line @typescript-eslint/ban-types
   | (string & {})
+
+/**
+ * Exa `/contents` freshness knob. Controls whether the page is fetched live
+ * or served from Exa's cache. Provider-specific, so it lives on
+ * `ExaContentsRequest`.
+ */
+export type ExaLivecrawl =
+  | "never"
+  | "fallback"
+  | "preferred"
+  | "always"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})