@pierre/storage 0.0.11 → 0.1.1

package/src/commit.ts

@@ -1,10 +1,16 @@
+import { inferRefUpdateReason, RefUpdateError } from './errors';
+import type { CommitPackAckRaw } from './schemas';
+import { commitPackAckSchema, commitPackResponseSchema, errorEnvelopeSchema } from './schemas';
 import type {
+	BlobLike,
 	CommitBuilder,
 	CommitFileOptions,
 	CommitFileSource,
-	CommitResponse,
+	CommitResult,
 	CommitTextFileOptions,
 	CreateCommitOptions,
+	ReadableStreamLike,
+	RefUpdate,
 } from './types';
 
 const MAX_CHUNK_BYTES = 4 * 1024 * 1024;
@@ -21,37 +27,22 @@ const BufferCtor: NodeBufferConstructor | undefined = (
 	globalThis as { Buffer?: NodeBufferConstructor }
 ).Buffer;
 
-interface ReadableStreamReaderLike<T> {
-	read(): Promise<{ value?: T; done: boolean }>;
-	releaseLock?(): void;
-}
-
-interface ReadableStreamLike<T> {
-	getReader(): ReadableStreamReaderLike<T>;
-}
-
-interface BlobLike {
-	stream(): unknown;
-}
-
 type ChunkSegment = {
 	chunk: Uint8Array;
 	eof: boolean;
 };
 
 interface CommitMetadataPayload {
-	target_ref: string;
-	base_ref?: string;
+	target_branch: string;
+	expected_head_sha?: string;
 	commit_message: string;
-	author?: {
+	author: {
 		name: string;
 		email: string;
-		date?: string;
 	};
 	committer?: {
 		name: string;
 		email: string;
-		date?: string;
 	};
 	files: Array<{
 		path: string;
@@ -69,7 +60,7 @@ interface CommitTransportRequest {
 }
 
 interface CommitTransport {
-	send(request: CommitTransportRequest): Promise<CommitResponse>;
+	send(request: CommitTransportRequest): Promise<CommitPackAck>;
 }
 
 interface CommitBuilderDeps {
@@ -86,6 +77,8 @@ type FileOperationState = {
 	streamFactory?: () => AsyncIterable<Uint8Array>;
 };
 
+type CommitPackAck = CommitPackAckRaw;
+
 export class CommitBuilderImpl implements CommitBuilder {
 	private readonly options: CreateCommitOptions;
 	private readonly getAuthToken: () => Promise<string>;
@@ -98,18 +91,31 @@ export class CommitBuilderImpl implements CommitBuilder {
 		this.getAuthToken = deps.getAuthToken;
 		this.transport = deps.transport;
 
-		const trimmedTarget = this.options.targetRef?.trim();
+		const trimmedTarget = this.options.targetBranch?.trim();
 		const trimmedMessage = this.options.commitMessage?.trim();
+		const trimmedAuthorName = this.options.author?.name?.trim();
+		const trimmedAuthorEmail = this.options.author?.email?.trim();
+
 		if (!trimmedTarget) {
-			throw new Error('createCommit targetRef is required');
+			throw new Error('createCommit targetBranch is required');
+		}
+		if (trimmedTarget.startsWith('refs/')) {
+			throw new Error('createCommit targetBranch must not include refs/ prefix');
 		}
 		if (!trimmedMessage) {
 			throw new Error('createCommit commitMessage is required');
 		}
-		this.options.targetRef = trimmedTarget;
+		if (!trimmedAuthorName || !trimmedAuthorEmail) {
+			throw new Error('createCommit author name and email are required');
+		}
+		this.options.targetBranch = trimmedTarget;
 		this.options.commitMessage = trimmedMessage;
-		if (typeof this.options.baseRef === 'string') {
-			this.options.baseRef = this.options.baseRef.trim();
+		this.options.author = {
+			name: trimmedAuthorName,
+			email: trimmedAuthorEmail,
+		};
+		if (typeof this.options.expectedHeadSha === 'string') {
+			this.options.expectedHeadSha = this.options.expectedHeadSha.trim();
 		}
 	}
 
@@ -135,11 +141,21 @@ export class CommitBuilderImpl implements CommitBuilder {
 		contents: string,
 		options?: CommitTextFileOptions,
 	): CommitBuilder {
-		const encoding = options?.encoding;
-		if (encoding && encoding !== 'utf8' && encoding !== 'utf-8') {
-			throw new Error(`Unsupported encoding "${encoding}". Only UTF-8 is supported.`);
+		const encoding = options?.encoding ?? 'utf8';
+		const normalizedEncoding = encoding === 'utf-8' ? 'utf8' : encoding;
+		let data: Uint8Array;
+		if (normalizedEncoding === 'utf8') {
+			data = new TextEncoder().encode(contents);
+		} else if (BufferCtor) {
+			data = BufferCtor.from(
+				contents,
+				normalizedEncoding as Parameters<NodeBufferConstructor['from']>[1],
+			);
+		} else {
+			throw new Error(
+				`Unsupported encoding "${encoding}" in this environment. Non-UTF encodings require Node.js Buffer support.`,
+			);
 		}
-		const data = new TextEncoder().encode(contents);
 		return this.addFile(path, data, options);
 	}
 
@@ -154,7 +170,7 @@ export class CommitBuilderImpl implements CommitBuilder {
 		return this;
 	}
 
-	async send(): Promise<CommitResponse> {
+	async send(): Promise<CommitResult> {
 		this.ensureNotSent();
 		this.sent = true;
 
@@ -167,12 +183,13 @@ export class CommitBuilderImpl implements CommitBuilder {
 			}));
 
 		const authorization = await this.getAuthToken();
-		return this.transport.send({
+		const ack = await this.transport.send({
 			authorization,
 			signal: this.options.signal,
 			metadata,
 			blobs: blobEntries,
 		});
+		return buildCommitResult(ack);
 	}
 
 	private buildMetadata(): CommitMetadataPayload {
@@ -189,19 +206,23 @@ export class CommitBuilderImpl implements CommitBuilder {
 		});
 
 		const metadata: CommitMetadataPayload = {
-			target_ref: this.options.targetRef,
+			target_branch: this.options.targetBranch,
 			commit_message: this.options.commitMessage,
+			author: {
+				name: this.options.author.name,
+				email: this.options.author.email,
+			},
 			files,
 		};
 
-		if (this.options.baseRef) {
-			metadata.base_ref = this.options.baseRef;
-		}
-		if (this.options.author) {
-			metadata.author = { ...this.options.author };
+		if (this.options.expectedHeadSha) {
+			metadata.expected_head_sha = this.options.expectedHeadSha;
 		}
 		if (this.options.committer) {
-			metadata.committer = { ...this.options.committer };
+			metadata.committer = {
+				name: this.options.committer.name,
+				email: this.options.committer.email,
+			};
 		}
 
 		return metadata;
@@ -229,7 +250,7 @@ export class FetchCommitTransport implements CommitTransport {
 		this.url = `${trimmedBase}/api/v${config.version}/repos/commit-pack`;
 	}
 
-	async send(request: CommitTransportRequest): Promise<CommitResponse> {
+	async send(request: CommitTransportRequest): Promise<CommitPackAck> {
 		const bodyIterable = buildMessageIterable(request.metadata, request.blobs);
 		const body = toRequestBody(bodyIterable);
 
@@ -245,11 +266,16 @@ export class FetchCommitTransport implements CommitTransport {
 		});
 
 		if (!response.ok) {
-			const text = await response.text();
-			throw new Error(`createCommit request failed (${response.status}): ${text}`);
+			const { statusMessage, statusLabel, refUpdate } = await parseCommitPackError(response);
+			throw new RefUpdateError(statusMessage, {
+				status: statusLabel,
+				message: statusMessage,
+				refUpdate,
+			});
 		}
 
-		return (await response.json()) as CommitResponse;
+		const ack = commitPackAckSchema.parse(await response.json());
+		return ack;
 	}
 }
 
@@ -302,6 +328,36 @@ function buildMessageIterable(
 	};
 }
 
+function buildCommitResult(ack: CommitPackAck): CommitResult {
+	const refUpdate = toRefUpdate(ack.result);
+	if (!ack.result.success) {
+		throw new RefUpdateError(
+			ack.result.message ?? `Commit failed with status ${ack.result.status}`,
+			{
+				status: ack.result.status,
+				message: ack.result.message,
+				refUpdate,
+			},
+		);
+	}
+	return {
+		commitSha: ack.commit.commit_sha,
+		treeSha: ack.commit.tree_sha,
+		targetBranch: ack.commit.target_branch,
+		packBytes: ack.commit.pack_bytes,
+		blobCount: ack.commit.blob_count,
+		refUpdate,
+	};
+}
+
+function toRefUpdate(result: CommitPackAck['result']): RefUpdate {
+	return {
+		branch: result.branch,
+		oldSha: result.old_sha,
+		newSha: result.new_sha,
+	};
+}
+
 async function* chunkify(source: AsyncIterable<Uint8Array>): AsyncIterable<ChunkSegment> {
 	let pending: Uint8Array | null = null;
 	let produced = false;
@@ -369,6 +425,10 @@ async function* toAsyncIterable(source: CommitFileSource): AsyncIterable<Uint8Ar
 			return;
 		}
 	}
+	if (isReadableStreamLike(source)) {
+		yield* readReadableStream(source);
+		return;
+	}
 	if (isAsyncIterable(source)) {
 		for await (const chunk of source as AsyncIterable<unknown>) {
 			yield ensureUint8Array(chunk);
@@ -492,5 +552,98 @@ export function createCommitBuilder(deps: CommitBuilderDeps): CommitBuilder {
 }
 
 export function resolveCommitTtlSeconds(options?: { ttl?: number }): number {
-	return typeof options?.ttl === 'number' && options.ttl > 0 ? options.ttl : DEFAULT_TTL_SECONDS;
+	if (typeof options?.ttl === 'number' && options.ttl > 0) {
+		return options.ttl;
+	}
+	return DEFAULT_TTL_SECONDS;
+}
+
+async function parseCommitPackError(response: Response): Promise<{
+	statusMessage: string;
+	statusLabel: string;
+	refUpdate?: Partial<RefUpdate>;
+}> {
+	const fallbackMessage = `createCommit request failed (${response.status} ${response.statusText})`;
+	const cloned = response.clone();
+	let jsonBody: unknown;
+	try {
+		jsonBody = await cloned.json();
+	} catch {
+		jsonBody = undefined;
+	}
+
+	let textBody: string | undefined;
+	if (jsonBody === undefined) {
+		try {
+			textBody = await response.text();
+		} catch {
+			textBody = undefined;
+		}
+	}
+
+	const defaultStatus = (() => {
+		const inferred = inferRefUpdateReason(String(response.status));
+		return inferred === 'unknown' ? 'failed' : inferred;
+	})();
+	let statusLabel = defaultStatus;
+	let refUpdate: Partial<RefUpdate> | undefined;
+	let message: string | undefined;
+
+	if (jsonBody !== undefined) {
+		const parsedResponse = commitPackResponseSchema.safeParse(jsonBody);
+		if (parsedResponse.success) {
+			const result = parsedResponse.data.result;
+			if (typeof result.status === 'string' && result.status.trim() !== '') {
+				statusLabel = result.status.trim() as typeof statusLabel;
+			}
+			refUpdate = toPartialRefUpdateFields(result.branch, result.old_sha, result.new_sha);
+			if (typeof result.message === 'string' && result.message.trim() !== '') {
+				message = result.message.trim();
+			}
+		}
+
+		if (!message) {
+			const parsedError = errorEnvelopeSchema.safeParse(jsonBody);
+			if (parsedError.success) {
+				const trimmed = parsedError.data.error.trim();
+				if (trimmed) {
+					message = trimmed;
+				}
+			}
+		}
+	}
+
+	if (!message && typeof jsonBody === 'string' && jsonBody.trim() !== '') {
+		message = jsonBody.trim();
+	}
+
+	if (!message && textBody && textBody.trim() !== '') {
+		message = textBody.trim();
+	}
+
+	return {
+		statusMessage: message ?? fallbackMessage,
+		statusLabel,
+		refUpdate,
+	};
+}
+
+function toPartialRefUpdateFields(
+	branch?: string | null,
+	oldSha?: string | null,
+	newSha?: string | null,
+): Partial<RefUpdate> | undefined {
+	const refUpdate: Partial<RefUpdate> = {};
+
+	if (typeof branch === 'string' && branch.trim() !== '') {
+		refUpdate.branch = branch.trim();
+	}
+	if (typeof oldSha === 'string' && oldSha.trim() !== '') {
+		refUpdate.oldSha = oldSha.trim();
+	}
+	if (typeof newSha === 'string' && newSha.trim() !== '') {
+		refUpdate.newSha = newSha.trim();
+	}
+
+	return Object.keys(refUpdate).length > 0 ? refUpdate : undefined;
 }

package/src/errors.ts

@@ -0,0 +1,50 @@
+import type { RefUpdate, RefUpdateReason } from './types';
+
+export interface RefUpdateErrorOptions {
+	status: string;
+	message?: string;
+	refUpdate?: Partial<RefUpdate>;
+	reason?: RefUpdateReason;
+}
+
+export class RefUpdateError extends Error {
+	public readonly status: string;
+	public readonly reason: RefUpdateReason;
+	public readonly refUpdate?: Partial<RefUpdate>;
+
+	constructor(message: string, options: RefUpdateErrorOptions) {
+		super(message);
+		this.name = 'RefUpdateError';
+		this.status = options.status;
+		this.reason = options.reason ?? inferRefUpdateReason(options.status);
+		this.refUpdate = options.refUpdate;
+	}
+}
+
+const REF_REASON_MAP: Record<string, RefUpdateReason> = {
+	precondition_failed: 'precondition_failed',
+	conflict: 'conflict',
+	not_found: 'not_found',
+	invalid: 'invalid',
+	timeout: 'timeout',
+	unauthorized: 'unauthorized',
+	forbidden: 'forbidden',
+	unavailable: 'unavailable',
+	internal: 'internal',
+	failed: 'failed',
+	ok: 'unknown',
+};
+
+export function inferRefUpdateReason(status?: string): RefUpdateReason {
+	if (!status) {
+		return 'unknown';
+	}
+
+	const trimmed = status.trim();
+	if (trimmed === '') {
+		return 'unknown';
+	}
+
+	const label = trimmed.toLowerCase();
+	return REF_REASON_MAP[label] ?? 'unknown';
+}

package/src/fetch.ts

@@ -1,16 +1,40 @@
+import { errorEnvelopeSchema } from './schemas';
 import type { ValidAPIVersion, ValidMethod, ValidPath } from './types';
 
 interface RequestOptions {
 	allowedStatus?: number[];
 }
 
+export class ApiError extends Error {
+	public readonly status: number;
+	public readonly statusText: string;
+	public readonly method: ValidMethod;
+	public readonly url: string;
+	public readonly body?: unknown;
+
+	constructor(params: {
+		message: string;
+		status: number;
+		statusText: string;
+		method: ValidMethod;
+		url: string;
+		body?: unknown;
+	}) {
+		super(params.message);
+		this.name = 'ApiError';
+		this.status = params.status;
+		this.statusText = params.statusText;
+		this.method = params.method;
+		this.url = params.url;
+		this.body = params.body;
+	}
+}
+
 export class ApiFetcher {
 	constructor(
 		private readonly API_BASE_URL: string,
 		private readonly version: ValidAPIVersion,
-	) {
-		console.log('api fetcher created', API_BASE_URL, version);
-	}
+	) {}
 
 	private getBaseUrl() {
 		return `${this.API_BASE_URL}/api/v${this.version}`;
@@ -46,9 +70,55 @@ export class ApiFetcher {
 
 		if (!response.ok) {
 			const allowed = options?.allowedStatus ?? [];
-			if (!allowed.includes(response.status)) {
-				throw new Error(`Failed to fetch ${method} ${requestUrl}: ${response.statusText}`);
+			if (allowed.includes(response.status)) {
+				return response;
 			}
+
+			let errorBody: unknown;
+			let message: string | undefined;
+			const contentType = response.headers.get('content-type') ?? '';
+
+			try {
+				if (contentType.includes('application/json')) {
+					errorBody = await response.json();
+				} else {
+					const text = await response.text();
+					errorBody = text;
+				}
+			} catch {
+				// Fallback to plain text if JSON parse failed after reading body
+				try {
+					errorBody = await response.text();
+				} catch {
+					errorBody = undefined;
+				}
+			}
+
+			if (typeof errorBody === 'string') {
+				const trimmed = errorBody.trim();
+				if (trimmed) {
+					message = trimmed;
+				}
+			} else if (errorBody && typeof errorBody === 'object') {
+				const parsedError = errorEnvelopeSchema.safeParse(errorBody);
+				if (parsedError.success) {
+					const trimmed = parsedError.data.error.trim();
+					if (trimmed) {
+						message = trimmed;
+					}
+				}
+			}
+
+			throw new ApiError({
+				message:
+					message ??
+					`Request ${method} ${requestUrl} failed with status ${response.status} ${response.statusText}`,
+				status: response.status,
+				statusText: response.statusText,
+				method,
+				url: requestUrl,
+				body: errorBody,
+			});
 		}
 		return response;
 	}