expandai 0.0.4 → 0.0.6

package/src/ApiClient.ts

@@ -1,450 +0,0 @@
-import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
-import { NodeHttpClient } from '@effect/platform-node'
-import { fetchObjectModeJson, fetchSnapshotSearch } from '@expandai/sdk/FetchJson'
-import * as Generated from '@expandai/sdk/Generated'
-import { decodeError, unexpectedStatus } from '@expandai/sdk/HttpClientHelpers'
-import { Data, DateTime, Duration, Effect, flow, Match, Option, Redacted, Schema } from 'effect'
-import { CLI_AUTHORIZATION_CLIENT_ID } from './Auth/Domain.js'
-import { BrowserOAuthService } from './BrowserOAuth.js'
-import { ConfigManager, OAuthConfig, OAuthTokenExpired } from './Config.js'
-import { CurrentRequestHeaders } from './Mcp/RequestHeaders.js'
-
-export class DeviceAuthorizationCreated extends Schema.Class<DeviceAuthorizationCreated>('DeviceAuthorizationCreated')({
-	deviceCode: Schema.Redacted(Schema.NonEmptyString),
-	userCode: Schema.NonEmptyString,
-	// `Schema.URL` decodes to a `URL`; the wire form stays a string. The CLI
-	// hands this to the user to open, so a malformed `appUrls.app` should fail
-	// here rather than in a browser.
-	verificationUri: Schema.URL,
-	// Whole seconds. A zero or negative `expiresIn` is a window that has already
-	// closed, so it must be positive.
-	expiresIn: Schema.Int.pipe(Schema.positive()),
-	// `interval` is RFC 8628's *minimum* wait between polls, so zero is
-	// meaningful — poll without delay. Only negative is nonsense, and it would
-	// make `nextPollAt` drift backwards forever.
-	interval: Schema.Int.pipe(Schema.nonNegative()),
-}) {}
-
-const ManualAuthorizationTokenResponse = Schema.Struct({
-	access_token: Schema.Redacted(Schema.NonEmptyString),
-	refresh_token: Schema.Redacted(Schema.NonEmptyString),
-	token_type: Schema.NonEmptyString,
-	expires_in: Schema.Number.pipe(Schema.positive()),
-	scope: Schema.optional(Schema.String),
-})
-
-export type ManualAuthorizationTokenResponse = typeof ManualAuthorizationTokenResponse.Type
-
-/**
- * RFC 8628 §3.5 poll outcomes. These are results, not errors: an agent-driven
- * CLI returns immediately on every one of them, and only a transport failure
- * is exceptional.
- */
-export type DevicePollOutcome =
-	| { readonly _tag: 'Tokens'; readonly token: ManualAuthorizationTokenResponse }
-	| { readonly _tag: 'Pending' }
-	| { readonly _tag: 'SlowDown' }
-	| { readonly _tag: 'Denied' }
-	| { readonly _tag: 'Expired' }
-	| { readonly _tag: 'Invalid' }
-	/**
-	 * The server refused for a reason a fresh code cannot fix — a misconfigured
-	 * client, resource, or scope. Distinct from `Invalid` because the recovery is
-	 * opposite: `Invalid` means start over, this means stop and report. Carries
-	 * the server's own `error` so the message names the actual cause instead of
-	 * guessing.
-	 */
-	| { readonly _tag: 'Refused'; readonly error: string; readonly description?: string }
-
-const ManualAuthorizationOperation = Schema.Literal('create', 'poll')
-
-export class ManualAuthorizationApiError extends Schema.TaggedError<ManualAuthorizationApiError>()(
-	'ManualAuthorizationApiError',
-	{
-		operation: ManualAuthorizationOperation,
-		kind: Schema.Literal('request_failed', 'rejected', 'invalid_response'),
-		status: Schema.optional(Schema.Number),
-		recoverable: Schema.Boolean,
-	},
-) {
-	get message() {
-		return this.kind === 'rejected'
-			? `Manual authorization ${this.operation} was rejected. Restart authorization if the problem persists.`
-			: `Manual authorization ${this.operation} could not be completed safely. Try again.`
-	}
-}
-
-/**
- * Single user-facing error for any failure crossing the API boundary. The
- * generated client raises a half-dozen status-specific tagged classes plus
- * transport/decode errors; we collapse them here so the rest of the app sees
- * one tag with a ready-made `.message` and never has to know about
- * `Generated.ts` types.
- */
-export class ApiRequestFailed extends Schema.TaggedError<ApiRequestFailed>()('ApiRequestFailed', {
-	detail: Schema.String,
-}) {
-	get message() {
-		return this.detail
-	}
-}
-
-// Derived rather than hand-written so codegen drift surfaces as a type error.
-type ClientError =
-	| Effect.Effect.Error<ReturnType<Generated.Client['fetchFetch']>>
-	| Effect.Effect.Error<ReturnType<Generated.Client['fetchFetchJson']>>
-	| Effect.Effect.Error<ReturnType<Generated.Client['fetchFetchSearch']>>
-	| Effect.Effect.Error<ReturnType<Generated.Client['fetchBatched']>>
-	| Effect.Effect.Error<ReturnType<Generated.Client['fetchGetBatched']>>
-type Issue = typeof Generated.Issue.Type
-type OAuthAuthMethod = typeof OAuthConfig.Type
-
-const OAUTH_REFRESH_SKEW = Duration.minutes(1)
-
-class OAuthAuthMethodChanged extends Data.TaggedError('OAuthAuthMethodChanged')<Record<string, never>> {}
-
-function getField(value: unknown, key: string): unknown {
-	return typeof value === 'object' && value !== null && key in value ? value[key as keyof typeof value] : undefined
-}
-
-function getStringField(value: unknown, key: string): string | undefined {
-	const field = getField(value, key)
-	return typeof field === 'string' ? field : undefined
-}
-
-function getIssueList(value: unknown): Issue[] {
-	const issues = getField(value, 'issues')
-	return Array.isArray(issues) ? (issues as Issue[]) : []
-}
-
-function getUnsupportedFields(value: unknown): string[] {
-	const unsupportedFields = getField(value, 'unsupportedFields')
-	return Array.isArray(unsupportedFields) ? unsupportedFields.filter((field) => typeof field === 'string') : []
-}
-
-function formatIssue({ path, message }: Issue): string {
-	const prefix = path.map((segment) => (typeof segment === 'object' ? segment.key : String(segment))).join('.')
-	return prefix ? `${prefix}: ${message}` : message
-}
-
-function formatApiFailure(error: ClientError): string {
-	switch (getStringField(error, '_tag')) {
-		case 'HttpApiDecodeError': {
-			const issues = getIssueList(error)
-			return issues.length === 0
-				? (getStringField(error, 'message') ?? 'Invalid request')
-				: issues.map(formatIssue).join('; ')
-		}
-		case 'AuthFailed':
-			return `Authentication failed (${getStringField(error, 'reason') ?? 'unknown'}). Run \`expandai login\` to re-authenticate.`
-		case 'AccessBlocked':
-			return 'Access blocked. Check your billing status or contact support.'
-		case 'BatchedIncludeUnsupported':
-			return `Unsupported batched include fields: ${getUnsupportedFields(error).join(', ')}.`
-		case 'FetchSnapshotSearchNotFound':
-			return 'Fetch snapshot not found.'
-		case 'PayloadTooLarge':
-			return 'Request payload is too large.'
-		case 'TooManyRequests':
-			return 'Rate limit exceeded — try again in a moment.'
-		case 'InternalError':
-			return 'The expand.ai API returned an internal error. Try again or contact support.'
-		case 'ServiceUnavailable':
-			return 'The expand.ai API is temporarily unavailable. Try again shortly.'
-		default:
-			return error instanceof Error ? error.message : (getStringField(error, 'message') ?? 'Expand API request failed.')
-	}
-}
-
-const liftApiError = <A, R>(self: Effect.Effect<A, ClientError, R>) =>
-	self.pipe(Effect.catchAll((error) => new ApiRequestFailed({ detail: formatApiFailure(error) })))
-
-/** Public, unauthenticated HTTP boundary for device-flow CLI authorization. */
-export class ManualAuthorizationApiClient extends Effect.Service<ManualAuthorizationApiClient>()(
-	'@expandai/cli/ManualAuthorizationApiClient',
-	{
-		dependencies: [NodeHttpClient.layer, ConfigManager.Default],
-		effect: Effect.gen(function* () {
-			const httpClient = yield* HttpClient.HttpClient
-			const configManager = yield* ConfigManager
-
-			const apiError = (
-				operation: typeof ManualAuthorizationOperation.Type,
-				kind: 'request_failed' | 'rejected' | 'invalid_response',
-				status?: number,
-			) =>
-				new ManualAuthorizationApiError({
-					operation,
-					kind,
-					status,
-					recoverable: kind !== 'invalid_response',
-				})
-
-			const create = Effect.fn('ManualAuthorizationApiClient.create')(function* (input: {
-				readonly harness: 'agent-harnesses'
-				readonly scope: 'project' | 'global'
-				readonly platform: string
-				readonly machineLabel: string
-				readonly cliVersion: string
-			}) {
-				const apiUrl = yield* configManager.getApiUrl()
-				const request = yield* HttpClientRequest.post(new URL('/v1/cli-authorization/device', apiUrl)).pipe(
-					HttpClientRequest.bodyJson(input),
-					Effect.mapError(() => apiError('create', 'request_failed')),
-				)
-				return yield* httpClient.execute(request).pipe(
-					Effect.flatMap((response) =>
-						response.status >= 200 && response.status < 300
-							? HttpClientResponse.schemaBodyJson(DeviceAuthorizationCreated)(response).pipe(
-									Effect.mapError(() => apiError('create', 'invalid_response')),
-								)
-							: Effect.fail(apiError('create', 'rejected', response.status)),
-					),
-					Effect.catchAll((error) =>
-						error instanceof ManualAuthorizationApiError
-							? Effect.fail(error)
-							: Effect.fail(apiError('create', 'request_failed')),
-					),
-				)
-			})
-
-			const PollErrorBody = Schema.Struct({
-				error: Schema.String,
-				error_description: Schema.optional(Schema.String),
-			})
-
-			/**
-			 * RFC 6749/8628 errors that describe the *request* rather than the state
-			 * of this particular code. Re-minting produces a code that fails
-			 * identically, so treating these as "expired" is what turns a
-			 * misconfiguration into an endless approve loop.
-			 */
-			const PERMANENT_REFUSALS = new Set([
-				'invalid_target',
-				'invalid_client',
-				'invalid_scope',
-				'unsupported_grant_type',
-				'unauthorized_client',
-				'invalid_request',
-			])
-
-			/**
-			 * One poll of the OAuth token endpoint (RFC 8628). Form-encoded, and
-			 * always against `/oauth2/token`: `/device/token` is the first-party
-			 * session path and the server rejects our client there by design.
-			 */
-			const poll = Effect.fn('ManualAuthorizationApiClient.poll')(function* (deviceCode: Redacted.Redacted<string>) {
-				const apiUrl = yield* configManager.getApiUrl()
-				const request = HttpClientRequest.post(new URL('/api/auth/oauth2/token', apiUrl)).pipe(
-					HttpClientRequest.bodyUrlParams({
-						grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-						device_code: Redacted.value(deviceCode),
-						client_id: CLI_AUTHORIZATION_CLIENT_ID,
-					}),
-				)
-				return yield* httpClient.execute(request).pipe(
-					Effect.flatMap(
-						Effect.fnUntraced(function* (response) {
-							if (response.status >= 200 && response.status < 300) {
-								const token = yield* HttpClientResponse.schemaBodyJson(ManualAuthorizationTokenResponse)(response).pipe(
-									Effect.mapError(() => apiError('poll', 'invalid_response')),
-								)
-								return { _tag: 'Tokens', token } satisfies DevicePollOutcome
-							}
-							if (response.status >= 500) return yield* apiError('poll', 'rejected', response.status)
-							const body = yield* HttpClientResponse.schemaBodyJson(PollErrorBody)(response).pipe(
-								Effect.mapError(() => apiError('poll', 'invalid_response')),
-							)
-							switch (body.error) {
-								case 'authorization_pending':
-									return { _tag: 'Pending' } satisfies DevicePollOutcome
-								case 'slow_down':
-									return { _tag: 'SlowDown' } satisfies DevicePollOutcome
-								case 'access_denied':
-									return { _tag: 'Denied' } satisfies DevicePollOutcome
-								case 'expired_token':
-									return { _tag: 'Expired' } satisfies DevicePollOutcome
-								default:
-									return PERMANENT_REFUSALS.has(body.error)
-										? ({
-												_tag: 'Refused',
-												error: body.error,
-												...(body.error_description === undefined ? {} : { description: body.error_description }),
-											} satisfies DevicePollOutcome)
-										: ({ _tag: 'Invalid' } satisfies DevicePollOutcome)
-							}
-						}),
-					),
-					Effect.catchAll((error) =>
-						error instanceof ManualAuthorizationApiError
-							? Effect.fail(error)
-							: Effect.fail(apiError('poll', 'request_failed')),
-					),
-				)
-			})
-
-			return { create, poll } as const
-		}),
-	},
-) {}
-
-/**
- * Resolves outgoing API auth per call. When the current request scope carries
- * an `Authorization` header (via `CurrentRequestHeaders`), that value is
- * forwarded; otherwise auth comes from `~/.config/expandai/config.json`.
- */
-export class ApiClient extends Effect.Service<ApiClient>()('@expandai/cli/ApiClient', {
-	dependencies: [NodeHttpClient.layer, ConfigManager.Default, BrowserOAuthService.Default],
-	scoped: Effect.gen(function* () {
-		const configManager = yield* ConfigManager
-		const browserOAuth = yield* BrowserOAuthService
-		const baseClient = yield* HttpClient.HttpClient
-		const refreshLock = yield* Effect.makeSemaphore(1)
-
-		const freshOAuthAccessToken = Effect.fn('ApiClient.freshOAuthAccessToken')(function* ({
-			accessToken,
-			expiresAt,
-			refreshToken,
-		}: OAuthAuthMethod) {
-			const now = yield* DateTime.now
-			const refreshThreshold = refreshToken === undefined ? now : DateTime.addDuration(now, OAUTH_REFRESH_SKEW)
-			if (DateTime.lessThan(refreshThreshold, expiresAt)) {
-				return Option.some(Redacted.value(accessToken))
-			}
-			return Option.none<string>()
-		})
-
-		const refreshOAuthToken = Effect.fn('ApiClient.refreshOAuthToken')(function* ({
-			refreshToken,
-			expiresAt,
-			clientId,
-		}: OAuthAuthMethod) {
-			if (refreshToken === undefined) {
-				return yield* new OAuthTokenExpired({ expiredAt: expiresAt })
-			}
-
-			const now = yield* DateTime.now
-			const token = yield* browserOAuth.refreshToken(Redacted.value(refreshToken), clientId)
-			if (token === undefined) {
-				return yield* new OAuthTokenExpired({ expiredAt: expiresAt })
-			}
-			const refreshedExpiresAt = DateTime.addDuration(now, token.expires_in)
-			const nextRefreshToken = token.refresh_token === undefined ? refreshToken : Redacted.make(token.refresh_token)
-			yield* configManager.updateConfig({
-				authMethod: OAuthConfig.make({
-					accessToken: Redacted.make(token.access_token),
-					refreshToken: nextRefreshToken,
-					expiresAt: refreshedExpiresAt,
-					clientId,
-				}),
-			})
-
-			return token.access_token
-		})
-
-		const oauthBearerToken = Effect.fn('ApiClient.oauthBearerToken')(function* (authMethod: OAuthAuthMethod) {
-			const alreadyFresh = yield* freshOAuthAccessToken(authMethod)
-			if (Option.isSome(alreadyFresh)) {
-				return alreadyFresh.value
-			}
-
-			return yield* refreshLock.withPermits(1)(
-				Effect.gen(function* () {
-					const { authMethod: persistedAuthMethod } = yield* configManager.loadConfig()
-					if (persistedAuthMethod._tag !== 'OAuth') {
-						return yield* new OAuthAuthMethodChanged({})
-					}
-
-					const persistedFresh = yield* freshOAuthAccessToken(persistedAuthMethod)
-					if (Option.isSome(persistedFresh)) {
-						return persistedFresh.value
-					}
-
-					return yield* refreshOAuthToken(persistedAuthMethod)
-				}),
-			)
-		})
-
-		// Resolved per call, not at construction. Effect Layers are globally
-		// memoized, so capturing CurrentRequestHeaders here once would freeze
-		// auth resolution to whatever was on the first request. Reading per
-		// call also keeps the OAuth `expiresAt` check live against `DateTime.now`.
-		// `Effect.serviceOption` reads the tag from the outer fiber context
-		// without leaking it into our R, so the API's per-request
-		// `Context.make(CurrentRequestHeaders, headers)` flows through and the
-		// stdio MCP path simply gets `Option.none` → empty headers.
-		const buildAuthedClientOnce = () =>
-			Effect.gen(function* () {
-				const forwardedHeaders = yield* Effect.serviceOption(CurrentRequestHeaders).pipe(
-					Effect.map(Option.getOrElse(() => ({}) as Record<string, string>)),
-				)
-				// header keys are lowercase per WHATWG Headers spec.
-				const forwardedAuth = Option.fromNullable(forwardedHeaders['authorization'])
-
-				if (Option.isSome(forwardedAuth)) {
-					// Forwarded path: caller owns the token's lifecycle (their session,
-					// their bearer). We don't re-check expiry — if it's stale the API
-					// will return 401. `OAuthTokenExpired` is for the *persisted*
-					// OAuth in the loadConfig branch only.
-					const apiUrl = yield* configManager.getApiUrl()
-					const mapRequest = flow(
-						HttpClientRequest.prependUrl(apiUrl.toString()),
-						HttpClientRequest.setHeader('authorization', forwardedAuth.value),
-					)
-					return baseClient.pipe(HttpClient.mapRequest(mapRequest))
-				}
-
-				const { authMethod, apiUrl } = yield* configManager.loadConfig()
-				const applyAuth = yield* Match.value(authMethod).pipe(
-					Match.tag('ApiKey', ({ apiKey }) =>
-						Effect.succeed(HttpClientRequest.setHeader('x-expand-api-key', Redacted.value(apiKey))),
-					),
-					Match.tag('OAuth', (authMethod) =>
-						oauthBearerToken(authMethod).pipe(Effect.map((accessToken) => HttpClientRequest.bearerToken(accessToken))),
-					),
-					Match.exhaustive,
-				)
-				const mapRequest = flow(HttpClientRequest.prependUrl(apiUrl.toString()), applyAuth)
-				return baseClient.pipe(HttpClient.mapRequest(mapRequest))
-			})
-		const buildAuthedClient = () =>
-			buildAuthedClientOnce().pipe(Effect.catchTag('OAuthAuthMethodChanged', () => buildAuthedClientOnce()))
-		const buildAuthed = () => buildAuthedClient().pipe(Effect.map(Generated.make))
-		const fetchMarkdown = (client: HttpClient.HttpClient, options: Parameters<Generated.Client['fetchFetch']>[0]) =>
-			HttpClientRequest.make('POST')('/v1/fetch').pipe(
-				HttpClientRequest.setUrlParams(options.params.include !== undefined ? { include: options.params.include } : {}),
-				(req) => Effect.orDie(HttpClientRequest.bodyJson(req, options.payload)),
-				Effect.flatMap((request) =>
-					Effect.flatMap(
-						client.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),
-						}),
-					),
-				),
-			)
-
-		return {
-			fetchFetch: (...args: Parameters<Generated.Client['fetchFetch']>) =>
-				buildAuthedClient().pipe(Effect.flatMap((client) => fetchMarkdown(client, ...args).pipe(liftApiError))),
-			fetchFetchResult: (...args: Parameters<Generated.Client['fetchFetchJson']>) =>
-				buildAuthedClient().pipe(Effect.flatMap((client) => fetchObjectModeJson(client, ...args).pipe(liftApiError))),
-			fetchFetchJson: (...args: Parameters<Generated.Client['fetchFetchJson']>) =>
-				buildAuthedClient().pipe(Effect.flatMap((client) => fetchObjectModeJson(client, ...args).pipe(liftApiError))),
-			fetchFetchSearch: (...args: Parameters<Generated.Client['fetchFetchSearch']>) =>
-				buildAuthedClient().pipe(Effect.flatMap((client) => fetchSnapshotSearch(client, ...args).pipe(liftApiError))),
-			fetchBatched: (...args: Parameters<Generated.Client['fetchBatched']>) =>
-				buildAuthed().pipe(Effect.flatMap((client) => client.fetchBatched(...args).pipe(liftApiError))),
-			fetchGetBatched: (...args: Parameters<Generated.Client['fetchGetBatched']>) =>
-				buildAuthed().pipe(Effect.flatMap((client) => client.fetchGetBatched(...args).pipe(liftApiError))),
-		} as const
-	}),
-}) {}

package/src/Auth/Domain.ts

@@ -1,63 +0,0 @@
-import { Schema } from 'effect'
-
-/**
- * The OAuth client for browser-approved CLI setup. Distinct from the
- * `expandai-cli` client that `expandai login` uses: that one keeps loopback
- * redirect URIs and must keep showing a consent screen, because Better Auth
- * matches loopback URIs without comparing the port.
- */
-export const CLI_AUTHORIZATION_CLIENT_ID = 'expandai-cli-browser'
-
-export const PendingInitKey = Schema.Struct({
-	apiOrigin: Schema.String,
-	clientId: Schema.Literal(CLI_AUTHORIZATION_CLIENT_ID),
-	harness: Schema.Literal('agent-harnesses'),
-	scope: Schema.Literal('project', 'global'),
-	canonicalScopeRoot: Schema.String,
-})
-
-export type PendingInitKey = typeof PendingInitKey.Type
-
-/**
- * One pending RFC 8628 device authorization. The `deviceCode` is the whole
- * credential — better-auth binds it to our client id server-side and it never
- * leaves this machine — so the record keeps the same 0600/no-symlink storage
- * discipline the PKCE verifier had.
- */
-export class PendingInitRecord extends Schema.Class<PendingInitRecord>('PendingInitRecord')({
-	key: PendingInitKey,
-	deviceCode: Schema.Redacted(Schema.String),
-	userCode: Schema.String,
-	verificationUri: Schema.String,
-	// RFC 8628 §3.5: current polling interval in seconds. `slow_down` adds five,
-	// permanently, so the backoff has to be persisted — each `init` invocation
-	// polls at most once and exits.
-	intervalSeconds: Schema.Number,
-	// Earliest wall-clock time the next poll may hit the network. An agent
-	// re-running `init` faster than the interval gets a local "still pending"
-	// instead of a request the server would answer with `slow_down`.
-	nextPollAt: Schema.DateTimeUtc,
-	approvalExpiresAt: Schema.DateTimeUtc,
-}) {}
-
-export class PendingInitCorrupt extends Schema.TaggedError<PendingInitCorrupt>()('PendingInitCorrupt', {
-	path: Schema.String,
-	error: Schema.Defect,
-}) {
-	readonly recoverable = true
-
-	get message() {
-		return `Pending authorization state at ${this.path} is corrupt and was left unchanged.`
-	}
-}
-
-export class PendingInitStorageError extends Schema.TaggedError<PendingInitStorageError>()('PendingInitStorageError', {
-	path: Schema.String,
-	error: Schema.Defect,
-}) {
-	readonly recoverable = true
-
-	get message() {
-		return `Could not access pending authorization state at ${this.path}.`
-	}
-}