@pierre/storage 0.0.9 → 0.0.11

package/package.json

@@ -1,39 +1,38 @@
 {
-	"name": "@pierre/storage",
-	"version": "0.0.9",
-	"description": "Pierre Git Storage SDK",
-	"license": "MIT",
-	"type": "module",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs",
-			"default": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"src"
-	],
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"prepublishOnly": "pnpm build"
-	},
-	"dependencies": {
-		"jose": "^5.10.0",
-		"snakecase-keys": "^9.0.2"
-	},
-	"devDependencies": {
-		"tsup": "8.5.0",
-		"typescript": "5.8.3",
-		"vitest": "3.2.4"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "@pierre/storage",
+  "version": "0.0.11",
+  "description": "Pierre Git Storage SDK",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "jose": "^5.10.0",
+    "snakecase-keys": "^9.0.2"
+  },
+  "devDependencies": {
+    "tsup": "8.5.0",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}

package/src/commit.ts

@@ -0,0 +1,496 @@
+import type {
+	CommitBuilder,
+	CommitFileOptions,
+	CommitFileSource,
+	CommitResponse,
+	CommitTextFileOptions,
+	CreateCommitOptions,
+} from './types';
+
+const MAX_CHUNK_BYTES = 4 * 1024 * 1024;
+const DEFAULT_TTL_SECONDS = 60 * 60;
+
+type NodeBuffer = Uint8Array & { toString(encoding?: string): string };
+interface NodeBufferConstructor {
+	from(data: Uint8Array): NodeBuffer;
+	from(data: string, encoding?: string): NodeBuffer;
+	isBuffer(value: unknown): value is NodeBuffer;
+}
+
+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;
+	commit_message: string;
+	author?: {
+		name: string;
+		email: string;
+		date?: string;
+	};
+	committer?: {
+		name: string;
+		email: string;
+		date?: string;
+	};
+	files: Array<{
+		path: string;
+		content_id: string;
+		operation?: 'upsert' | 'delete';
+		mode?: string;
+	}>;
+}
+
+interface CommitTransportRequest {
+	authorization: string;
+	signal?: AbortSignal;
+	metadata: CommitMetadataPayload;
+	blobs: Array<{ contentId: string; chunks: AsyncIterable<ChunkSegment> }>;
+}
+
+interface CommitTransport {
+	send(request: CommitTransportRequest): Promise<CommitResponse>;
+}
+
+interface CommitBuilderDeps {
+	options: CreateCommitOptions;
+	getAuthToken: () => Promise<string>;
+	transport: CommitTransport;
+}
+
+type FileOperationState = {
+	path: string;
+	contentId: string;
+	mode?: string;
+	operation: 'upsert' | 'delete';
+	streamFactory?: () => AsyncIterable<Uint8Array>;
+};
+
+export class CommitBuilderImpl implements CommitBuilder {
+	private readonly options: CreateCommitOptions;
+	private readonly getAuthToken: () => Promise<string>;
+	private readonly transport: CommitTransport;
+	private readonly operations: FileOperationState[] = [];
+	private sent = false;
+
+	constructor(deps: CommitBuilderDeps) {
+		this.options = { ...deps.options };
+		this.getAuthToken = deps.getAuthToken;
+		this.transport = deps.transport;
+
+		const trimmedTarget = this.options.targetRef?.trim();
+		const trimmedMessage = this.options.commitMessage?.trim();
+		if (!trimmedTarget) {
+			throw new Error('createCommit targetRef is required');
+		}
+		if (!trimmedMessage) {
+			throw new Error('createCommit commitMessage is required');
+		}
+		this.options.targetRef = trimmedTarget;
+		this.options.commitMessage = trimmedMessage;
+		if (typeof this.options.baseRef === 'string') {
+			this.options.baseRef = this.options.baseRef.trim();
+		}
+	}
+
+	addFile(path: string, source: CommitFileSource, options?: CommitFileOptions): CommitBuilder {
+		this.ensureNotSent();
+		const normalizedPath = this.normalizePath(path);
+		const contentId = randomContentId();
+		const mode = options?.mode ?? '100644';
+
+		this.operations.push({
+			path: normalizedPath,
+			contentId,
+			mode,
+			operation: 'upsert',
+			streamFactory: () => toAsyncIterable(source),
+		});
+
+		return this;
+	}
+
+	addFileFromString(
+		path: string,
+		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 data = new TextEncoder().encode(contents);
+		return this.addFile(path, data, options);
+	}
+
+	deletePath(path: string): CommitBuilder {
+		this.ensureNotSent();
+		const normalizedPath = this.normalizePath(path);
+		this.operations.push({
+			path: normalizedPath,
+			contentId: randomContentId(),
+			operation: 'delete',
+		});
+		return this;
+	}
+
+	async send(): Promise<CommitResponse> {
+		this.ensureNotSent();
+		this.sent = true;
+
+		const metadata = this.buildMetadata();
+		const blobEntries = this.operations
+			.filter((op) => op.operation === 'upsert' && op.streamFactory)
+			.map((op) => ({
+				contentId: op.contentId,
+				chunks: chunkify(op.streamFactory!()),
+			}));
+
+		const authorization = await this.getAuthToken();
+		return this.transport.send({
+			authorization,
+			signal: this.options.signal,
+			metadata,
+			blobs: blobEntries,
+		});
+	}
+
+	private buildMetadata(): CommitMetadataPayload {
+		const files = this.operations.map((op) => {
+			const entry: CommitMetadataPayload['files'][number] = {
+				path: op.path,
+				content_id: op.contentId,
+				operation: op.operation,
+			};
+			if (op.mode) {
+				entry.mode = op.mode;
+			}
+			return entry;
+		});
+
+		const metadata: CommitMetadataPayload = {
+			target_ref: this.options.targetRef,
+			commit_message: this.options.commitMessage,
+			files,
+		};
+
+		if (this.options.baseRef) {
+			metadata.base_ref = this.options.baseRef;
+		}
+		if (this.options.author) {
+			metadata.author = { ...this.options.author };
+		}
+		if (this.options.committer) {
+			metadata.committer = { ...this.options.committer };
+		}
+
+		return metadata;
+	}
+
+	private ensureNotSent(): void {
+		if (this.sent) {
+			throw new Error('createCommit builder cannot be reused after send()');
+		}
+	}
+
+	private normalizePath(path: string): string {
+		if (!path || typeof path !== 'string' || path.trim() === '') {
+			throw new Error('File path must be a non-empty string');
+		}
+		return path.replace(/^\//, '');
+	}
+}
+
+export class FetchCommitTransport implements CommitTransport {
+	private readonly url: string;
+
+	constructor(config: { baseUrl: string; version: number }) {
+		const trimmedBase = config.baseUrl.replace(/\/+$/, '');
+		this.url = `${trimmedBase}/api/v${config.version}/repos/commit-pack`;
+	}
+
+	async send(request: CommitTransportRequest): Promise<CommitResponse> {
+		const bodyIterable = buildMessageIterable(request.metadata, request.blobs);
+		const body = toRequestBody(bodyIterable);
+
+		const response = await fetch(this.url, {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${request.authorization}`,
+				'Content-Type': 'application/x-ndjson',
+				Accept: 'application/json',
+			},
+			body: body as any,
+			signal: request.signal,
+		});
+
+		if (!response.ok) {
+			const text = await response.text();
+			throw new Error(`createCommit request failed (${response.status}): ${text}`);
+		}
+
+		return (await response.json()) as CommitResponse;
+	}
+}
+
+function toRequestBody(iterable: AsyncIterable<Uint8Array>): unknown {
+	const readableStreamCtor = (
+		globalThis as { ReadableStream?: new (underlyingSource: unknown) => unknown }
+	).ReadableStream;
+	if (typeof readableStreamCtor === 'function') {
+		const iterator = iterable[Symbol.asyncIterator]();
+		return new readableStreamCtor({
+			async pull(controller: { enqueue(chunk: Uint8Array): void; close(): void }) {
+				const { value, done } = await iterator.next();
+				if (done) {
+					controller.close();
+					return;
+				}
+				controller.enqueue(value!);
+			},
+			async cancel(reason: unknown) {
+				if (typeof iterator.return === 'function') {
+					await iterator.return(reason);
+				}
+			},
+		});
+	}
+	return iterable;
+}
+
+function buildMessageIterable(
+	metadata: CommitMetadataPayload,
+	blobs: Array<{ contentId: string; chunks: AsyncIterable<ChunkSegment> }>,
+): AsyncIterable<Uint8Array> {
+	const encoder = new TextEncoder();
+	return {
+		async *[Symbol.asyncIterator]() {
+			yield encoder.encode(`${JSON.stringify({ metadata })}\n`);
+			for (const blob of blobs) {
+				for await (const segment of blob.chunks) {
+					const payload = {
+						blob_chunk: {
+							content_id: blob.contentId,
+							data: base64Encode(segment.chunk),
+							eof: segment.eof,
+						},
+					};
+					yield encoder.encode(`${JSON.stringify(payload)}\n`);
+				}
+			}
+		},
+	};
+}
+
+async function* chunkify(source: AsyncIterable<Uint8Array>): AsyncIterable<ChunkSegment> {
+	let pending: Uint8Array | null = null;
+	let produced = false;
+
+	for await (const value of source) {
+		const bytes = value;
+
+		if (pending && pending.byteLength === MAX_CHUNK_BYTES) {
+			yield { chunk: pending, eof: false };
+			produced = true;
+			pending = null;
+		}
+
+		const merged: Uint8Array = pending ? concatChunks(pending, bytes) : bytes;
+		pending = null;
+
+		let cursor: Uint8Array = merged;
+		while (cursor.byteLength > MAX_CHUNK_BYTES) {
+			const chunk: Uint8Array = cursor.slice(0, MAX_CHUNK_BYTES);
+			cursor = cursor.slice(MAX_CHUNK_BYTES);
+			yield { chunk, eof: false };
+			produced = true;
+		}
+
+		pending = cursor;
+	}
+
+	if (pending) {
+		yield { chunk: pending, eof: true };
+		produced = true;
+	}
+
+	if (!produced) {
+		yield { chunk: new Uint8Array(0), eof: true };
+	}
+}
+
+async function* toAsyncIterable(source: CommitFileSource): AsyncIterable<Uint8Array> {
+	if (typeof source === 'string') {
+		yield new TextEncoder().encode(source);
+		return;
+	}
+	if (source instanceof Uint8Array) {
+		yield source;
+		return;
+	}
+	if (source instanceof ArrayBuffer) {
+		yield new Uint8Array(source);
+		return;
+	}
+	if (ArrayBuffer.isView(source)) {
+		yield new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+		return;
+	}
+	if (isBlobLike(source)) {
+		const stream = source.stream();
+		if (isAsyncIterable(stream)) {
+			for await (const chunk of stream as AsyncIterable<unknown>) {
+				yield ensureUint8Array(chunk);
+			}
+			return;
+		}
+		if (isReadableStreamLike(stream)) {
+			yield* readReadableStream(stream);
+			return;
+		}
+	}
+	if (isAsyncIterable(source)) {
+		for await (const chunk of source as AsyncIterable<unknown>) {
+			yield ensureUint8Array(chunk);
+		}
+		return;
+	}
+	if (isIterable(source)) {
+		for (const chunk of source as Iterable<unknown>) {
+			yield ensureUint8Array(chunk);
+		}
+		return;
+	}
+	throw new Error('Unsupported file source for createCommit');
+}
+
+async function* readReadableStream(stream: ReadableStreamLike<unknown>): AsyncIterable<Uint8Array> {
+	const reader = stream.getReader();
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) {
+				break;
+			}
+			if (value !== undefined) {
+				yield ensureUint8Array(value);
+			}
+		}
+	} finally {
+		reader.releaseLock?.();
+	}
+}
+
+function ensureUint8Array(value: unknown): Uint8Array {
+	if (value instanceof Uint8Array) {
+		return value;
+	}
+	if (value instanceof ArrayBuffer) {
+		return new Uint8Array(value);
+	}
+	if (ArrayBuffer.isView(value)) {
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	}
+	if (typeof value === 'string') {
+		return new TextEncoder().encode(value);
+	}
+	if (BufferCtor && BufferCtor.isBuffer(value)) {
+		return value as Uint8Array;
+	}
+	throw new Error('Unsupported chunk type; expected binary data');
+}
+
+function isBlobLike(value: unknown): value is BlobLike {
+	return (
+		typeof value === 'object' && value !== null && typeof (value as BlobLike).stream === 'function'
+	);
+}
+
+function isReadableStreamLike<T>(value: unknown): value is ReadableStreamLike<T> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as ReadableStreamLike<T>).getReader === 'function'
+	);
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Symbol.asyncIterator in (value as Record<string, unknown>)
+	);
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Symbol.iterator in (value as Record<string, unknown>)
+	);
+}
+
+function concatChunks(a: Uint8Array, b: Uint8Array): Uint8Array {
+	if (a.byteLength === 0) {
+		return b;
+	}
+	if (b.byteLength === 0) {
+		return a;
+	}
+	const merged = new Uint8Array(a.byteLength + b.byteLength);
+	merged.set(a, 0);
+	merged.set(b, a.byteLength);
+	return merged;
+}
+
+function base64Encode(bytes: Uint8Array): string {
+	if (BufferCtor) {
+		return BufferCtor.from(bytes).toString('base64');
+	}
+	let binary = '';
+	for (let i = 0; i < bytes.byteLength; i++) {
+		binary += String.fromCharCode(bytes[i]);
+	}
+	const btoaFn = (globalThis as { btoa?: (data: string) => string }).btoa;
+	if (typeof btoaFn === 'function') {
+		return btoaFn(binary);
+	}
+	throw new Error('Base64 encoding is not supported in this environment');
+}
+
+function randomContentId(): string {
+	const cryptoObj = globalThis.crypto;
+	if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
+		return cryptoObj.randomUUID();
+	}
+	const random = Math.random().toString(36).slice(2);
+	return `cid-${Date.now().toString(36)}-${random}`;
+}
+
+export function createCommitBuilder(deps: CommitBuilderDeps): CommitBuilder {
+	return new CommitBuilderImpl(deps);
+}
+
+export function resolveCommitTtlSeconds(options?: { ttl?: number }): number {
+	return typeof options?.ttl === 'number' && options.ttl > 0 ? options.ttl : DEFAULT_TTL_SECONDS;
+}

package/src/index.ts

@@ -6,8 +6,11 @@
 
 import { importPKCS8, SignJWT } from 'jose';
 import snakecaseKeys from 'snakecase-keys';
+import { createCommitBuilder, FetchCommitTransport, resolveCommitTtlSeconds } from './commit';
 import { ApiFetcher } from './fetch';
 import type {
+	CommitBuilder,
+	CreateCommitOptions,
 	CreateRepoOptions,
 	FindOneOptions,
 	GetBranchDiffOptions,
@@ -26,8 +29,8 @@ import type {
 	ListFilesOptions,
 	ListFilesResponse,
 	OverrideableGitStorageOptions,
+	PullUpstreamOptions,
 	Repo,
-	RepullOptions,
 	ValidAPIVersion,
 } from './types';
 
@@ -219,7 +222,7 @@ class RepoImpl implements Repo {
 		return (await response.json()) as GetCommitResponse;
 	}
 
-	async repull(options: RepullOptions): Promise<void> {
+	async pullUpstream(options: PullUpstreamOptions): Promise<void> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:write'],
 			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
@@ -231,14 +234,33 @@ class RepoImpl implements Repo {
 			body.ref = options.ref;
 		}
 
-		const response = await this.api.post({ path: 'repos/repull', body }, jwt);
+		const response = await this.api.post({ path: 'repos/pull-upstream', body }, jwt);
 
 		if (response.status !== 202) {
-			throw new Error(`Repull failed: ${response.status} ${await response.text()}`);
+			throw new Error(`Pull Upstream failed: ${response.status} ${await response.text()}`);
 		}
 
 		return;
 	}
+
+	createCommit(options: CreateCommitOptions): CommitBuilder {
+		const version = this.options.apiVersion ?? API_VERSION;
+		const baseUrl = this.options.apiBaseUrl ?? API_BASE_URL;
+		const transport = new FetchCommitTransport({ baseUrl, version });
+		const ttlSeconds = resolveCommitTtlSeconds(options);
+		const builderOptions: CreateCommitOptions = { ...options, ttl: ttlSeconds };
+		const getAuthToken = () =>
+			this.generateJWT(this.id, {
+				permissions: ['git:write'],
+				ttl: ttlSeconds,
+			});
+
+		return createCommitBuilder({
+			options: builderOptions,
+			getAuthToken,
+			transport,
+		});
+	}
 }
 
 export class GitStorage {