@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/services/Ai/index.d.ts

@@ -0,0 +1,13 @@
+import { Context, Layer } from 'effect';
+import type { Generic } from '../../domain/errors';
+import { Api, type ApiService } from '../Api';
+import type { AiService } from './types';
+export type * from './types';
+export declare const make: (api: ApiService) => AiService;
+export type _Generic = Generic;
+declare const Ai_base: Context.TagClass<Ai, "Ai", AiService>;
+export declare class Ai extends Ai_base {
+    static Default: Layer.Layer<Ai, never, Api>;
+}
+/** Build an Ai layer from an explicit ApiService (tests). */
+export declare const layer: (api: ApiService) => Layer.Layer<Ai>;

package/dist/src/services/Ai/index.js

@@ -0,0 +1,127 @@
+import { Context, Effect, Layer } from 'effect';
+import { Api } from '../Api';
+import { makeOverview } from './overview';
+import { makeByArticle, makeList, makeMatchById } from './resources';
+import { makeCreateTask, makeWaitForTask } from './tasks';
+export const make = (api) => {
+    const createTask = makeCreateTask(api);
+    const list = makeList(api);
+    const matchById = makeMatchById(api);
+    const byArticle = makeByArticle(api);
+    const translationsByArticle = (refId, opts) => opts?.lang
+        ? api.request(`/ai/translations/article/${refId}`, {
+            query: { lang: opts.lang },
+        })
+        : api.request(`/ai/translations/ref/${refId}`);
+    return {
+        // -- generate
+        regenSummary: (input) => createTask('summary', '/ai/summaries/task', {
+            refId: input.refId,
+            ...(input.targetLanguages?.length
+                ? { targetLanguages: [...input.targetLanguages] }
+                : {}),
+            ...(input.force ? { force: true } : {}),
+        }),
+        translate: (input) => createTask('translation', '/ai/translations/task', {
+            refId: input.refId,
+            targetLanguages: [...input.targetLanguages],
+            ...(input.force ? { force: true } : {}),
+        }),
+        refreshInsights: (input) => createTask('insights', '/ai/insights/task', {
+            refId: input.refId,
+            ...(input.targetLanguages?.length
+                ? { targetLanguages: [...input.targetLanguages] }
+                : {}),
+            ...(input.force ? { force: true } : {}),
+        }),
+        translateSummary: (input) => createTask('summary_translation', '/ai/summaries/task/translate', {
+            refId: input.refId,
+            targetLang: input.targetLang,
+            ...(input.force ? { force: true } : {}),
+        }, {
+            sourceMissingHint: 'no base summary to translate — run `mxs ai summary regen` first',
+        }),
+        translateInsights: (input) => createTask('insights_translation', '/ai/insights/task/translate', {
+            refId: input.refId,
+            targetLang: input.targetLang,
+            ...(input.force ? { force: true } : {}),
+        }, {
+            sourceMissingHint: 'no base insights to translate — run `mxs ai insights refresh` first',
+        }),
+        runTts: (input) => createTask('tts', '/ai/tts/task', {
+            refId: input.refId,
+            ...(input.targetLanguages?.length
+                ? { langs: [...input.targetLanguages] }
+                : {}),
+            ...(input.force ? { force: true } : {}),
+        }),
+        waitForTask: makeWaitForTask(api),
+        // -- tts
+        listTts: list('/ai/tts', '/', '/grouped'),
+        getTtsByArticle: (refId) => api.request(`/ai/tts/ref/${refId}`),
+        discoverTtsVoices: (q) => api.request('/ai/tts/voices', {
+            query: { providerId: q.providerId, model: q.model },
+        }),
+        deleteTts: (id) => api.request(`/ai/tts/${id}`, { method: 'DELETE' }).pipe(Effect.asVoid),
+        // -- overview
+        ...makeOverview(api),
+        // -- summary
+        listSummaries: list('/ai/summaries', '/', '/grouped'),
+        getSummary: (id) => matchById('/ai/summaries', id, ['summaries']),
+        getSummariesByArticle: byArticle('/ai/summaries'),
+        updateSummary: (id, patch) => api.request(`/ai/summaries/${id}`, { method: 'PATCH', body: patch }),
+        deleteSummary: (id) => api
+            .request(`/ai/summaries/${id}`, { method: 'DELETE' })
+            .pipe(Effect.asVoid),
+        // -- translation
+        listTranslations: list('/ai/translations', null, '/grouped'),
+        getTranslation: (id) => matchById('/ai/translations', id, ['translations']),
+        getTranslationsByArticle: translationsByArticle,
+        getTranslationLanguages: (refId) => api.request(`/ai/translations/article/${refId}/languages`),
+        updateTranslation: (id, patch) => api.request(`/ai/translations/${id}`, { method: 'PATCH', body: patch }),
+        deleteTranslation: (id) => api
+            .request(`/ai/translations/${id}`, { method: 'DELETE' })
+            .pipe(Effect.asVoid),
+        // -- insights
+        listInsights: list('/ai/insights', '/', '/grouped'),
+        getInsights: (id) => matchById('/ai/insights', id, ['insights']),
+        getInsightsByArticle: byArticle('/ai/insights'),
+        updateInsights: (id, patch) => api.request(`/ai/insights/${id}`, { method: 'PATCH', body: patch }),
+        deleteInsights: (id) => api
+            .request(`/ai/insights/${id}`, { method: 'DELETE' })
+            .pipe(Effect.asVoid),
+        // -- entries
+        listEntries: (q) => api.request('/ai/translations/entries', {
+            query: {
+                page: q.page,
+                size: q.size,
+                keyPath: q.keyPath,
+                lang: q.lang,
+            },
+        }),
+        generateEntries: (input) => api.request('/ai/translations/entries/generate', {
+            method: 'POST',
+            body: {
+                ...(input.keyPaths?.length ? { keyPaths: [...input.keyPaths] } : {}),
+                ...(input.targetLangs?.length
+                    ? { targetLangs: [...input.targetLangs] }
+                    : {}),
+            },
+        }),
+        updateEntry: (id, patch) => api.request(`/ai/translations/entries/${id}`, {
+            method: 'PATCH',
+            body: patch,
+        }),
+        deleteEntry: (id) => api
+            .request(`/ai/translations/entries/${id}`, { method: 'DELETE' })
+            .pipe(Effect.asVoid),
+    };
+};
+export class Ai extends Context.Tag('Ai')() {
+    static Default = Layer.effect(Ai, Effect.gen(function* () {
+        const api = yield* Api;
+        return make(api);
+    }));
+}
+/** Build an Ai layer from an explicit ApiService (tests). */
+export const layer = (api) => Layer.succeed(Ai, make(api));

package/dist/src/services/Ai/overview.d.ts

@@ -0,0 +1,7 @@
+import type { Effect } from 'effect';
+import type { ApiError, ApiService } from '../Api';
+import type { AiOverviewListQuery } from './types';
+export declare const makeOverview: (api: ApiService) => {
+    listOverview: (q: AiOverviewListQuery) => Effect.Effect<unknown, ApiError>;
+    getOverviewByArticle: (refId: string) => Effect.Effect<unknown, ApiError>;
+};

package/dist/src/services/Ai/overview.js

@@ -0,0 +1,11 @@
+export const makeOverview = (api) => ({
+    listOverview: (q) => api.request('/ai/overview/grouped', {
+        query: {
+            page: q.page,
+            size: q.size,
+            search: q.search,
+            type: q.type,
+        },
+    }),
+    getOverviewByArticle: (refId) => api.request(`/ai/overview/article/${refId}`),
+});

package/dist/src/services/Ai/resources.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from 'effect';
+import { AiRecordNotFound } from '../../domain/errors';
+import type { ApiError, ApiService } from '../Api';
+import type { AiByArticleOptions, AiListQuery } from './types';
+export declare const makeList: (api: ApiService) => <Q extends AiListQuery>(base: string, flatPath: string | null, groupedPath: string) => (q: Q) => Effect.Effect<unknown, ApiError>;
+export declare const makeMatchById: (api: ApiService) => (base: string, id: string, itemKeys: ReadonlyArray<string>) => Effect.Effect<unknown, AiRecordNotFound | ApiError>;
+export declare const makeByArticle: (api: ApiService) => (base: string) => (refId: string, opts?: AiByArticleOptions) => Effect.Effect<unknown, ApiError>;

package/dist/src/services/Ai/resources.js

@@ -0,0 +1,59 @@
+import { Effect } from 'effect';
+import { AiRecordNotFound } from '../../domain/errors';
+import { asRecord, unwrapData } from './shared';
+export const makeList = (api) => (base, flatPath, groupedPath) => (q) => api.request(q.grouped || flatPath === null
+    ? `${base}${groupedPath}`
+    : `${base}${flatPath}`, {
+    query: {
+        page: q.page,
+        size: q.size,
+        search: q.search,
+    },
+});
+const groupedItems = (group, itemKeys) => {
+    const record = asRecord(group);
+    for (const key of itemKeys) {
+        const value = record[key];
+        if (Array.isArray(value))
+            return value;
+    }
+    return [];
+};
+export const makeMatchById = (api) => (base, id, itemKeys) => Effect.gen(function* () {
+    // Try grouped pagination; flatten and match by id. Capped scan to avoid
+    // unbounded pagination on enormous datasets.
+    const MAX_PAGES = 50;
+    const SIZE = 50;
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const raw = yield* api.request(`${base}/grouped`, {
+            query: { page, size: SIZE },
+        });
+        const data = unwrapData(raw);
+        const groups = Array.isArray(data) ? data : [];
+        for (const group of groups) {
+            for (const item of groupedItems(group, itemKeys)) {
+                const r = asRecord(item);
+                if (typeof r.id === 'string' && r.id === id)
+                    return item;
+            }
+        }
+        const pagination = asRecord(asRecord(asRecord(raw).meta).pagination);
+        const totalPages = typeof pagination.totalPages === 'number'
+            ? pagination.totalPages
+            : groups.length < SIZE
+                ? page
+                : page + 1;
+        if (page >= totalPages)
+            break;
+    }
+    return yield* Effect.fail(new AiRecordNotFound({
+        message: `AI record not found: ${id}`,
+        ref: id,
+    }));
+});
+export const makeByArticle = (api) => (base) => (refId, opts) => api.request(`${base}/article/${refId}`, {
+    query: {
+        lang: opts?.lang,
+        onlyDb: opts?.onlyDb,
+    },
+});

package/dist/src/services/Ai/shared.d.ts

@@ -0,0 +1,2 @@
+export declare const unwrapData: (raw: unknown) => unknown;
+export declare const asRecord: (value: unknown) => Record<string, unknown>;

package/dist/src/services/Ai/shared.js

@@ -0,0 +1,11 @@
+export const unwrapData = (raw) => {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const env = raw;
+        if ('data' in env)
+            return env.data;
+    }
+    return raw;
+};
+export const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};

package/dist/src/services/Ai/tasks.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from 'effect';
+import { AiTaskCreateFailed, AiTaskFailed } from '../../domain/errors';
+import type { ApiError, ApiService } from '../Api';
+import type { AiTaskCreateResult, AiTaskFinalView, AiTaskType, AiWaitOptions } from './types';
+export declare const makeCreateTask: (api: ApiService) => (type: AiTaskType, path: string, body: Record<string, unknown>, opts?: {
+    sourceMissingHint?: string;
+}) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+export declare const makeWaitForTask: (api: ApiService) => (taskId: string, options: AiWaitOptions) => Effect.Effect<AiTaskFinalView, AiTaskFailed | ApiError>;

package/dist/src/services/Ai/tasks.js

@@ -0,0 +1,144 @@
+import { Effect } from 'effect';
+import { AiTaskCreateFailed, AiTaskFailed } from '../../domain/errors';
+import { asRecord, unwrapData } from './shared';
+const readCreateTask = (raw) => {
+    const inner = asRecord(unwrapData(raw));
+    return {
+        taskId: typeof inner.taskId === 'string' ? inner.taskId : undefined,
+        created: typeof inner.created === 'boolean' ? inner.created : undefined,
+        reason: typeof inner.reason === 'string' ? inner.reason : undefined,
+    };
+};
+const readTaskRecord = (raw) => {
+    const inner = asRecord(unwrapData(raw));
+    const result = asRecord(inner.result);
+    const payload = asRecord(inner.payload);
+    const errField = inner.error;
+    return {
+        status: typeof inner.status === 'string'
+            ? inner.status
+            : undefined,
+        totalCost: typeof inner.totalCost === 'number' || typeof inner.totalCost === 'string'
+            ? inner.totalCost
+            : undefined,
+        totalTokens: typeof inner.totalTokens === 'number' ||
+            typeof inner.totalTokens === 'string'
+            ? inner.totalTokens
+            : undefined,
+        resultIds: Array.isArray(inner.resultIds)
+            ? inner.resultIds
+            : Array.isArray(result.resultIds)
+                ? result.resultIds
+                : undefined,
+        payload: {
+            refId: typeof payload.refId === 'string' ? payload.refId : undefined,
+            targetLanguages: Array.isArray(payload.targetLanguages)
+                ? payload.targetLanguages
+                : undefined,
+        },
+        error: typeof errField === 'string'
+            ? { message: errField }
+            : errField && typeof errField === 'object'
+                ? errField
+                : undefined,
+        errorMessage: typeof inner.errorMessage === 'string' ? inner.errorMessage : undefined,
+    };
+};
+const toNumber = (v) => {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+};
+const TERMINAL = new Set([
+    'completed',
+    'partial_failed',
+    'succeeded',
+    'failed',
+    'cancelled',
+]);
+const DEFAULT_POLL_MS = 1000;
+const resolvePollMs = (override) => {
+    const envRaw = process.env.MXS_AI_POLL_MS;
+    if (override && override > 0)
+        return override;
+    if (envRaw) {
+        const n = Number(envRaw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_POLL_MS;
+};
+export const makeCreateTask = (api) => (type, path, body, opts) => Effect.gen(function* () {
+    const raw = yield* api.request(path, { method: 'POST', body });
+    const env = readCreateTask(raw);
+    if (!env.taskId) {
+        return yield* Effect.fail(new AiTaskCreateFailed({
+            message: env.reason === 'source-missing' && opts?.sourceMissingHint
+                ? opts.sourceMissingHint
+                : 'server returned no taskId',
+            details: raw,
+        }));
+    }
+    return {
+        taskId: env.taskId,
+        created: env.created ?? true,
+        type,
+        refId: typeof body.refId === 'string' ? body.refId : '',
+        targetLanguages: Array.isArray(body.targetLanguages)
+            ? body.targetLanguages
+            : Array.isArray(body.langs)
+                ? body.langs
+                : typeof body.targetLang === 'string'
+                    ? [body.targetLang]
+                    : undefined,
+    };
+});
+export const makeWaitForTask = (api) => (taskId, options) => Effect.gen(function* () {
+    const pollMs = resolvePollMs(options.pollMs);
+    let lastStatus;
+    const pollOnce = () => api.request(`/tasks/${taskId}`).pipe(Effect.flatMap((raw) => {
+        const rec = readTaskRecord(raw);
+        const status = (rec.status ?? 'pending');
+        if (status !== lastStatus) {
+            lastStatus = status;
+            options.onProgress?.(`[ai] task ${status}…`);
+        }
+        if (TERMINAL.has(status))
+            return Effect.succeed({ rec, status });
+        return Effect.sleep(`${pollMs} millis`).pipe(Effect.flatMap(() => pollOnce()));
+    }));
+    const { rec, status } = yield* pollOnce();
+    const final = {
+        type: options.type,
+        taskId,
+        status,
+        refId: rec.payload?.refId,
+        targetLanguages: rec.payload?.targetLanguages,
+        totalTokens: toNumber(rec.totalTokens),
+        totalCost: toNumber(rec.totalCost),
+        resultIds: rec.resultIds,
+        error: typeof rec.error === 'object'
+            ? rec.error.message
+                ? { message: rec.error.message }
+                : undefined
+            : rec.errorMessage
+                ? { message: rec.errorMessage }
+                : undefined,
+    };
+    if (status === 'failed' ||
+        status === 'cancelled' ||
+        status === 'partial_failed') {
+        return yield* Effect.fail(new AiTaskFailed({
+            taskId,
+            status,
+            message: final.error?.message ?? `AI task ${status} (id=${taskId})`,
+            details: final,
+        }));
+    }
+    return final;
+});

package/dist/src/services/Ai/types.d.ts

@@ -0,0 +1,130 @@
+import type { Effect } from 'effect';
+import type { AiRecordNotFound, AiTaskCreateFailed, AiTaskFailed } from '../../domain/errors';
+import type { ApiError } from '../Api';
+export type AiTaskType = 'summary' | 'summary_translation' | 'translation' | 'insights' | 'insights_translation' | 'tts';
+export type AiTaskStatus = 'pending' | 'queued' | 'running' | 'completed' | 'partial_failed' | 'succeeded' | 'failed' | 'cancelled';
+export interface AiTaskCreateResult {
+    readonly taskId: string;
+    readonly created: boolean;
+    readonly type: AiTaskType;
+    readonly refId: string;
+    readonly targetLanguages?: ReadonlyArray<string>;
+}
+export interface AiTaskFinalView {
+    readonly type: AiTaskType;
+    readonly taskId: string;
+    readonly status: AiTaskStatus;
+    readonly refId?: string;
+    readonly targetLanguages?: ReadonlyArray<string>;
+    readonly totalTokens?: number;
+    readonly totalCost?: number;
+    readonly resultIds?: ReadonlyArray<string>;
+    readonly error?: {
+        readonly message: string;
+    };
+}
+export interface AiTaskCreateInput {
+    readonly refId: string;
+    readonly targetLanguages?: ReadonlyArray<string>;
+    readonly force?: boolean;
+}
+export interface AiTaskTranslateInput {
+    readonly refId: string;
+    readonly targetLanguages: ReadonlyArray<string>;
+    readonly force?: boolean;
+}
+export interface AiSingleTranslateInput {
+    readonly refId: string;
+    readonly targetLang: string;
+    readonly force?: boolean;
+}
+export interface AiWaitOptions {
+    readonly type: AiTaskType;
+    readonly pollMs?: number;
+    /** Stderr progress emitter; receives a transition message per state change. */
+    readonly onProgress?: (message: string) => void;
+}
+export interface AiListQuery {
+    readonly page?: number;
+    readonly size?: number;
+    readonly grouped?: boolean;
+    readonly search?: string;
+}
+export interface AiVoicesQuery {
+    readonly providerId: string;
+    readonly model: string;
+}
+export type AiOverviewType = 'post' | 'note' | 'page';
+export interface AiOverviewListQuery {
+    readonly page?: number;
+    readonly size?: number;
+    readonly search?: string;
+    readonly type?: AiOverviewType;
+}
+export interface AiEntryListQuery {
+    readonly page?: number;
+    readonly size?: number;
+    readonly keyPath?: string;
+    readonly lang?: string;
+}
+export interface AiEntryGenerateInput {
+    readonly keyPaths?: ReadonlyArray<string>;
+    readonly targetLangs?: ReadonlyArray<string>;
+}
+export interface AiSummaryPatch {
+    readonly summary: string;
+}
+export interface AiInsightsPatch {
+    readonly content: string;
+}
+export interface AiTranslationPatch {
+    title?: string;
+    text?: string;
+    subtitle?: string | null;
+    summary?: string;
+    tags?: ReadonlyArray<string>;
+    content?: string;
+}
+export interface AiEntryPatch {
+    readonly translatedText: string;
+}
+export interface AiByArticleOptions {
+    readonly lang?: string;
+    readonly onlyDb?: boolean;
+}
+export type AiServiceError = ApiError | AiTaskCreateFailed | AiTaskFailed | AiRecordNotFound;
+export interface AiService {
+    readonly regenSummary: (input: AiTaskCreateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly translate: (input: AiTaskTranslateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly refreshInsights: (input: AiTaskCreateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly translateSummary: (input: AiSingleTranslateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly translateInsights: (input: AiSingleTranslateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly runTts: (input: AiTaskCreateInput) => Effect.Effect<AiTaskCreateResult, AiTaskCreateFailed | ApiError>;
+    readonly waitForTask: (taskId: string, options: AiWaitOptions) => Effect.Effect<AiTaskFinalView, AiTaskFailed | ApiError>;
+    readonly listSummaries: (q: AiListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly getSummary: (id: string) => Effect.Effect<unknown, AiRecordNotFound | ApiError>;
+    readonly getSummariesByArticle: (refId: string, opts?: AiByArticleOptions) => Effect.Effect<unknown, ApiError>;
+    readonly updateSummary: (id: string, patch: AiSummaryPatch) => Effect.Effect<unknown, ApiError>;
+    readonly deleteSummary: (id: string) => Effect.Effect<void, ApiError>;
+    readonly listTranslations: (q: AiListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly getTranslation: (id: string) => Effect.Effect<unknown, AiRecordNotFound | ApiError>;
+    readonly getTranslationsByArticle: (refId: string, opts?: AiByArticleOptions) => Effect.Effect<unknown, ApiError>;
+    readonly getTranslationLanguages: (refId: string) => Effect.Effect<unknown, ApiError>;
+    readonly updateTranslation: (id: string, patch: AiTranslationPatch) => Effect.Effect<unknown, ApiError>;
+    readonly deleteTranslation: (id: string) => Effect.Effect<void, ApiError>;
+    readonly listInsights: (q: AiListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly getInsights: (id: string) => Effect.Effect<unknown, AiRecordNotFound | ApiError>;
+    readonly getInsightsByArticle: (refId: string, opts?: AiByArticleOptions) => Effect.Effect<unknown, ApiError>;
+    readonly updateInsights: (id: string, patch: AiInsightsPatch) => Effect.Effect<unknown, ApiError>;
+    readonly deleteInsights: (id: string) => Effect.Effect<void, ApiError>;
+    readonly listTts: (q: AiListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly getTtsByArticle: (refId: string) => Effect.Effect<unknown, ApiError>;
+    readonly discoverTtsVoices: (q: AiVoicesQuery) => Effect.Effect<unknown, ApiError>;
+    readonly deleteTts: (id: string) => Effect.Effect<void, ApiError>;
+    readonly listOverview: (q: AiOverviewListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly getOverviewByArticle: (refId: string) => Effect.Effect<unknown, ApiError>;
+    readonly listEntries: (q: AiEntryListQuery) => Effect.Effect<unknown, ApiError>;
+    readonly generateEntries: (input: AiEntryGenerateInput) => Effect.Effect<unknown, ApiError>;
+    readonly updateEntry: (id: string, patch: AiEntryPatch) => Effect.Effect<unknown, ApiError>;
+    readonly deleteEntry: (id: string) => Effect.Effect<void, ApiError>;
+}

package/dist/src/services/Ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/Api.d.ts

@@ -0,0 +1,67 @@
+import { HttpClient } from '@effect/platform';
+import type { Schema } from 'effect';
+import { Context, Effect, Layer } from 'effect';
+import { AuthDenied, AuthExpired, Generic, NetworkDns, NetworkRefused, NetworkTimeout, ResourceNotFound, ServerError, ValidationFailed, WriteRequiresExplicit } from '../domain/errors';
+import { Auth } from './Auth';
+import { Config, type StoreOverrides } from './Config';
+export type ApiMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+export interface ApiRequestOptions<A = unknown, I = unknown> {
+    readonly method?: ApiMethod;
+    readonly body?: unknown;
+    readonly query?: Readonly<Record<string, unknown>>;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+    /**
+     * Decoder for the response payload. When omitted, the raw parsed body is
+     * returned (likely an object or string, never undefined for non-204
+     * responses).
+     */
+    readonly schema?: Schema.Schema<A, I>;
+}
+/**
+ * Per-run overrides + UX flags that Wave 2 command code can supply when
+ * instantiating the Api layer via `Api.layer(...)`.
+ *
+ * - `overrides`: passed straight to `Config.resolve` — supports the global
+ *   flags `--api-url`, `--token`, `--api-key`, `--profile` and their env
+ *   equivalents.
+ * - `verbose` / `quiet`: control the production banner and `METHOD URL →
+ *   STATUS (Xms)` verbose log lines; they match the today's CLI behavior.
+ */
+export interface ApiOptions {
+    readonly overrides?: StoreOverrides;
+    readonly verbose?: boolean;
+    readonly quiet?: boolean;
+    /**
+     * When true, short-circuit writes (POST / PATCH / PUT / DELETE) BEFORE any
+     * network call. The body that would have been sent is surfaced via the
+     * returned value (`{ ok: true, dryRun: true, ... }`); reads pass through
+     * unchanged. Mirrors the v0.2.x `--dry-run` global flag.
+     */
+    readonly dryRun?: boolean;
+    /**
+     * When set, append `?lang=<code>` to GET / read-only requests so the server
+     * returns the localized variant. Writes are untouched. Mirrors the v0.2.x
+     * `--lang <code>` flag.
+     */
+    readonly lang?: string;
+}
+export type ApiError = AuthExpired | AuthDenied | ValidationFailed | ResourceNotFound | ServerError | NetworkTimeout | NetworkDns | NetworkRefused | WriteRequiresExplicit | Generic;
+export interface ApiService {
+    /** Issue a request against the active profile's `apiBase`. */
+    readonly request: <A = unknown, I = unknown>(path: string, options?: ApiRequestOptions<A, I>) => Effect.Effect<A, ApiError>;
+    /** Lower-level helper returning the raw parsed body without schema decoding. */
+    readonly raw: (path: string, options?: Omit<ApiRequestOptions, 'schema'>) => Effect.Effect<unknown, ApiError>;
+}
+declare const Api_base: Context.TagClass<Api, "Api", ApiService>;
+export declare class Api extends Api_base {
+    /**
+     * Default Layer: no overrides, banner + verbose enabled per env / config.
+     * Wave 2 entry-point (`bin/mxs.ts`) should use `Api.layer({...})` to wire
+     * flag-derived overrides through.
+     */
+    static Default: Layer.Layer<Api, never, Config | Auth | HttpClient.HttpClient>;
+    /** Build an Api Layer with command-specified overrides + UX flags. */
+    static layer(opts: ApiOptions): Layer.Layer<Api, never, Config | Auth | HttpClient.HttpClient>;
+}
+export {};