/**
 * Asset Upload Service
 *
 * Single primitive for "store a binary, create a wrapper entity that
 * points at it." Used by both the standalone `POST /api/repos/:repo/assets`
 * route and the multi-file import dispatcher when it sees a binary
 * extension.
 *
 * Flow per file:
 *   1. Validate extension against `ASSET_UPLOAD_EXTENSIONS`.
 *   2. Create the `asset` entity with stub frontmatter (collision-retry
 *      on entity_id, same `foo`→`foo-2` semantics as import-service).
 *   3. Upload the binary via `graph.uploadAsset` — picks R2 or local
 *      filesystem from the workspace's asset config.
 *   4. PDFs: extract text + page count via `pdf-parse`, write the text
 *      to a sidecar at `<workspace>/.studiograph/assets-text/asset/{id}.txt`
 *      so the vector indexer can RAG it without bloating the markdown body.
 *   5. Update the entity with the resolved `asset_url` and per-kind
 *      metadata (`pages`, future `width`/`height`).
 */
import type { BaseGraphManager } from '../core/graph.js';
import type { AssetKind } from '../core/validation.js';
import type { GitUser } from './git.js';
export interface UploadAssetOptions {
    graph: BaseGraphManager;
    /** Original filename from the client. May contain path segments — only the basename is used. */
    filename: string;
    buffer: Buffer;
    /** Repo-relative folder for the new entity's .md file. Empty/undefined = repo root. */
    folderPath?: string;
    /** Override entity name; defaults to title-cased slug of the filename stem. */
    name?: string;
    user?: GitUser;
    /** Defer git commit so the caller can batch (e.g. multi-file imports). Default false. */
    skipCommit?: boolean;
    /** Workspace root used to anchor the PDF text sidecar at
     *  `<workspacePath>/.studiograph/assets-text/asset/{id}.txt`. When
     *  undefined, sidecars are not written (the asset still uploads). */
    workspacePath?: string;
    /** Auth user id of the uploader (web). Recorded in the asset index for the
     *  uploader+owner delete rule. Omit for CLI/import — stored as null. */
    uploaderUserId?: string | null;
}
export interface UploadAssetResult {
    entityId: string;
    entityType: 'asset';
    /** Absolute path of the created `.md` entity file. */
    filePath: string;
    asset_url: string;
    asset_kind: AssetKind;
    asset_size: number;
    pages?: number;
    /** Sidecar path when one was written (PDF only). Caller can include in batched commit's extraPaths. */
    sidecarPath?: string;
}
export declare function uploadAsset(opts: UploadAssetOptions): Promise<UploadAssetResult>;
