@pierre/storage 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pierre/storage",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "Pierre Git Storage SDK",
 	"license": "MIT",
 	"type": "module",

package/src/index.ts

@@ -9,20 +9,25 @@ import snakecaseKeys from 'snakecase-keys';
 import { createCommitBuilder, FetchCommitTransport, resolveCommitTtlSeconds } from './commit';
 import { FetchDiffCommitTransport, sendCommitFromDiff } from './diff-commit';
 import { RefUpdateError } from './errors';
-import { ApiFetcher } from './fetch';
+import { ApiError, ApiFetcher } from './fetch';
 import type { RestoreCommitAckRaw } from './schemas';
 import {
 	branchDiffResponseSchema,
 	commitDiffResponseSchema,
 	createBranchResponseSchema,
+	errorEnvelopeSchema,
 	grepResponseSchema,
 	listBranchesResponseSchema,
 	listCommitsResponseSchema,
 	listFilesResponseSchema,
+	listReposResponseSchema,
+	noteReadResponseSchema,
+	noteWriteResponseSchema,
 	restoreCommitAckSchema,
 	restoreCommitResponseSchema,
 } from './schemas';
 import type {
+	AppendNoteOptions,
 	BranchInfo,
 	CommitBuilder,
 	CommitInfo,
@@ -32,7 +37,9 @@ import type {
 	CreateBranchResult,
 	CreateCommitFromDiffOptions,
 	CreateCommitOptions,
+	CreateNoteOptions,
 	CreateRepoOptions,
+	DeleteNoteOptions,
 	DeleteRepoOptions,
 	DeleteRepoResult,
 	DiffFileState,
@@ -46,6 +53,8 @@ import type {
 	GetCommitDiffResponse,
 	GetCommitDiffResult,
 	GetFileOptions,
+	GetNoteOptions,
+	GetNoteResult,
 	GetRemoteURLOptions,
 	GitStorageOptions,
 	GrepFileMatch,
@@ -60,6 +69,10 @@ import type {
 	ListCommitsResult,
 	ListFilesOptions,
 	ListFilesResult,
+	ListReposOptions,
+	ListReposResponse,
+	ListReposResult,
+	NoteWriteResult,
 	PullUpstreamOptions,
 	RawBranchInfo,
 	RawCommitInfo,
@@ -114,6 +127,23 @@ const RESTORE_COMMIT_ALLOWED_STATUS = [
 	504, // Gateway Timeout - long-running storage operations
 ] as const;
 
+const NOTE_WRITE_ALLOWED_STATUS = [
+	400, // Bad Request - validation errors
+	401, // Unauthorized - missing/invalid auth header
+	403, // Forbidden - missing git:write scope
+	404, // Not Found - repo or note lookup failures
+	408, // Request Timeout - client cancelled
+	409, // Conflict - concurrent ref updates
+	412, // Precondition Failed - optimistic concurrency
+	422, // Unprocessable Entity - metadata issues
+	429, // Too Many Requests - upstream throttling
+	499, // Client Closed Request - storage cancellation
+	500, // Internal Server Error - generic failure
+	502, // Bad Gateway - storage/gateway bridge issues
+	503, // Service Unavailable - storage selection failures
+	504, // Gateway Timeout - long-running storage operations
+] as const;
+
 function resolveInvocationTtlSeconds(
 	options?: { ttl?: number },
 	defaultValue: number = DEFAULT_TOKEN_TTL_SECONDS,
@@ -337,6 +367,26 @@ function transformCreateBranchResult(raw: CreateBranchResponse): CreateBranchRes
 	};
 }
 
+function transformListReposResult(raw: ListReposResponse): ListReposResult {
+	return {
+		repos: raw.repos.map((repo) => ({
+			repoId: repo.repo_id,
+			url: repo.url,
+			defaultBranch: repo.default_branch,
+			createdAt: repo.created_at,
+			baseRepo: repo.base_repo
+				? {
+						provider: repo.base_repo.provider,
+						owner: repo.base_repo.owner,
+						name: repo.base_repo.name,
+					}
+				: undefined,
+		})),
+		nextCursor: raw.next_cursor ?? undefined,
+		hasMore: raw.has_more,
+	};
+}
+
 function transformGrepLine(raw: { line_number: number; text: string; type: string }): GrepLine {
 	return {
 		lineNumber: raw.line_number,
@@ -355,6 +405,119 @@ function transformGrepFileMatch(raw: {
 	};
 }
 
+function transformNoteReadResult(raw: {
+	sha: string;
+	note: string;
+	ref_sha: string;
+}): GetNoteResult {
+	return {
+		sha: raw.sha,
+		note: raw.note,
+		refSha: raw.ref_sha,
+	};
+}
+
+function transformNoteWriteResult(raw: {
+	sha: string;
+	target_ref: string;
+	base_commit?: string;
+	new_ref_sha: string;
+	result: { success: boolean; status: string; message?: string };
+}): NoteWriteResult {
+	return {
+		sha: raw.sha,
+		targetRef: raw.target_ref,
+		baseCommit: raw.base_commit,
+		newRefSha: raw.new_ref_sha,
+		result: {
+			success: raw.result.success,
+			status: raw.result.status,
+			message: raw.result.message,
+		},
+	};
+}
+
+function buildNoteWriteBody(
+	sha: string,
+	note: string,
+	action: 'add' | 'append',
+	options: { expectedRefSha?: string; author?: { name: string; email: string } },
+): Record<string, unknown> {
+	const body: Record<string, unknown> = {
+		sha,
+		action,
+		note,
+	};
+
+	const expectedRefSha = options.expectedRefSha?.trim();
+	if (expectedRefSha) {
+		body.expected_ref_sha = expectedRefSha;
+	}
+
+	if (options.author) {
+		const authorName = options.author.name?.trim();
+		const authorEmail = options.author.email?.trim();
+		if (!authorName || !authorEmail) {
+			throw new Error('note author name and email are required when provided');
+		}
+		body.author = {
+			name: authorName,
+			email: authorEmail,
+		};
+	}
+
+	return body;
+}
+
+async function parseNoteWriteResponse(
+	response: Response,
+	method: 'POST' | 'DELETE',
+): Promise<NoteWriteResult> {
+	let jsonBody: unknown;
+	const contentType = response.headers.get('content-type') ?? '';
+	try {
+		if (contentType.includes('application/json')) {
+			jsonBody = await response.json();
+		} else {
+			jsonBody = await response.text();
+		}
+	} catch {
+		jsonBody = undefined;
+	}
+
+	if (jsonBody && typeof jsonBody === 'object') {
+		const parsed = noteWriteResponseSchema.safeParse(jsonBody);
+		if (parsed.success) {
+			return transformNoteWriteResult(parsed.data);
+		}
+		const parsedError = errorEnvelopeSchema.safeParse(jsonBody);
+		if (parsedError.success) {
+			throw new ApiError({
+				message: parsedError.data.error,
+				status: response.status,
+				statusText: response.statusText,
+				method,
+				url: response.url,
+				body: jsonBody,
+			});
+		}
+	}
+
+	const fallbackMessage =
+		typeof jsonBody === 'string' && jsonBody.trim() !== ''
+			? jsonBody.trim()
+			: `Request ${method} ${response.url} failed with status ${response.status} ${response.statusText}`;
+
+	throw new ApiError({
+		message: fallbackMessage,
+		status: response.status,
+		statusText: response.statusText,
+		method,
+		url: response.url,
+		body: jsonBody,
+	});
+}
+
 /**
  * Implementation of the Repo interface
  */
@@ -500,6 +663,154 @@ class RepoImpl implements Repo {
 		});
 	}
 
+	async getNote(options: GetNoteOptions): Promise<GetNoteResult> {
+		const sha = options?.sha?.trim();
+		if (!sha) {
+			throw new Error('getNote sha is required');
+		}
+
+		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl,
+		});
+
+		const response = await this.api.get({ path: 'repos/notes', params: { sha } }, jwt);
+		const raw = noteReadResponseSchema.parse(await response.json());
+		return transformNoteReadResult(raw);
+	}
+
+	async createNote(options: CreateNoteOptions): Promise<NoteWriteResult> {
+		const sha = options?.sha?.trim();
+		if (!sha) {
+			throw new Error('createNote sha is required');
+		}
+
+		const note = options?.note?.trim();
+		if (!note) {
+			throw new Error('createNote note is required');
+		}
+
+		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:write'],
+			ttl,
+		});
+
+		const body = buildNoteWriteBody(sha, note, 'add', {
+			expectedRefSha: options.expectedRefSha,
+			author: options.author,
+		});
+
+		const response = await this.api.post({ path: 'repos/notes', body }, jwt, {
+			allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS],
+		});
+
+		const result = await parseNoteWriteResponse(response, 'POST');
+		if (!result.result.success) {
+			throw new RefUpdateError(
+				result.result.message ?? `createNote failed with status ${result.result.status}`,
+				{
+					status: result.result.status,
+					message: result.result.message,
+					refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha),
+				},
+			);
+		}
+		return result;
+	}
+
+	async appendNote(options: AppendNoteOptions): Promise<NoteWriteResult> {
+		const sha = options?.sha?.trim();
+		if (!sha) {
+			throw new Error('appendNote sha is required');
+		}
+
+		const note = options?.note?.trim();
+		if (!note) {
+			throw new Error('appendNote note is required');
+		}
+
+		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:write'],
+			ttl,
+		});
+
+		const body = buildNoteWriteBody(sha, note, 'append', {
+			expectedRefSha: options.expectedRefSha,
+			author: options.author,
+		});
+
+		const response = await this.api.post({ path: 'repos/notes', body }, jwt, {
+			allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS],
+		});
+
+		const result = await parseNoteWriteResponse(response, 'POST');
+		if (!result.result.success) {
+			throw new RefUpdateError(
+				result.result.message ?? `appendNote failed with status ${result.result.status}`,
+				{
+					status: result.result.status,
+					message: result.result.message,
+					refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha),
+				},
+			);
+		}
+		return result;
+	}
+
+	async deleteNote(options: DeleteNoteOptions): Promise<NoteWriteResult> {
+		const sha = options?.sha?.trim();
+		if (!sha) {
+			throw new Error('deleteNote sha is required');
+		}
+
+		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:write'],
+			ttl,
+		});
+
+		const body: Record<string, unknown> = {
+			sha,
+		};
+
+		const expectedRefSha = options.expectedRefSha?.trim();
+		if (expectedRefSha) {
+			body.expected_ref_sha = expectedRefSha;
+		}
+
+		if (options.author) {
+			const authorName = options.author.name?.trim();
+			const authorEmail = options.author.email?.trim();
+			if (!authorName || !authorEmail) {
+				throw new Error('deleteNote author name and email are required when provided');
+			}
+			body.author = {
+				name: authorName,
+				email: authorEmail,
+			};
+		}
+
+		const response = await this.api.delete({ path: 'repos/notes', body }, jwt, {
+			allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS],
+		});
+
+		const result = await parseNoteWriteResponse(response, 'DELETE');
+		if (!result.result.success) {
+			throw new RefUpdateError(
+				result.result.message ?? `deleteNote failed with status ${result.result.status}`,
+				{
+					status: result.result.status,
+					message: result.result.message,
+					refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha),
+				},
+			);
+		}
+		return result;
+	}
+
 	async getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResult> {
 		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
 		const jwt = await this.generateJWT(this.id, {
@@ -916,6 +1227,36 @@ export class GitStorage {
 		return new RepoImpl(repoId, defaultBranch, this.options, this.generateJWT.bind(this));
 	}
 
+	/**
+	 * List repositories for the authenticated organization
+	 * @returns Paginated repositories list
+	 */
+	async listRepos(options?: ListReposOptions): Promise<ListReposResult> {
+		const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+		const jwt = await this.generateJWT('org', {
+			permissions: ['org:read'],
+			ttl,
+		});
+
+		let params: Record<string, string> | undefined;
+		if (options?.cursor || typeof options?.limit === 'number') {
+			params = {};
+			if (options.cursor) {
+				params.cursor = options.cursor;
+			}
+			if (typeof options.limit === 'number') {
+				params.limit = options.limit.toString();
+			}
+		}
+
+		const response = await this.api.get({ path: 'repos', params }, jwt);
+		const raw = listReposResponseSchema.parse(await response.json());
+		return transformListReposResult({
+			...raw,
+			next_cursor: raw.next_cursor ?? undefined,
+		});
+	}
+
 	/**
 	 * Find a repository by ID
 	 * @param options The search options

package/src/schemas.ts

@@ -34,6 +34,46 @@ export const listCommitsResponseSchema = z.object({
 	has_more: z.boolean(),
 });
 
+export const repoBaseInfoSchema = z.object({
+	provider: z.string(),
+	owner: z.string(),
+	name: z.string(),
+});
+
+export const repoInfoSchema = z.object({
+	repo_id: z.string(),
+	url: z.string(),
+	default_branch: z.string(),
+	created_at: z.string(),
+	base_repo: repoBaseInfoSchema.optional().nullable(),
+});
+
+export const listReposResponseSchema = z.object({
+	repos: z.array(repoInfoSchema),
+	next_cursor: z.string().nullable().optional(),
+	has_more: z.boolean(),
+});
+
+export const noteReadResponseSchema = z.object({
+	sha: z.string(),
+	note: z.string(),
+	ref_sha: z.string(),
+});
+
+export const noteResultSchema = z.object({
+	success: z.boolean(),
+	status: z.string(),
+	message: z.string().optional(),
+});
+
+export const noteWriteResponseSchema = z.object({
+	sha: z.string(),
+	target_ref: z.string(),
+	base_commit: z.string().optional(),
+	new_ref_sha: z.string(),
+	result: noteResultSchema,
+});
+
 export const diffStatsSchema = z.object({
 	files: z.number(),
 	additions: z.number(),
@@ -162,6 +202,11 @@ export type RawBranchInfo = z.infer<typeof branchInfoSchema>;
 export type ListBranchesResponseRaw = z.infer<typeof listBranchesResponseSchema>;
 export type RawCommitInfo = z.infer<typeof commitInfoRawSchema>;
 export type ListCommitsResponseRaw = z.infer<typeof listCommitsResponseSchema>;
+export type RawRepoBaseInfo = z.infer<typeof repoBaseInfoSchema>;
+export type RawRepoInfo = z.infer<typeof repoInfoSchema>;
+export type ListReposResponseRaw = z.infer<typeof listReposResponseSchema>;
+export type NoteReadResponseRaw = z.infer<typeof noteReadResponseSchema>;
+export type NoteWriteResponseRaw = z.infer<typeof noteWriteResponseSchema>;
 export type RawFileDiff = z.infer<typeof diffFileRawSchema>;
 export type RawFilteredFile = z.infer<typeof filteredFileRawSchema>;
 export type GetBranchDiffResponseRaw = z.infer<typeof branchDiffResponseSchema>;

package/src/types.ts

@@ -9,10 +9,15 @@ import type {
 	ListBranchesResponseRaw,
 	ListCommitsResponseRaw,
 	ListFilesResponseRaw,
+	ListReposResponseRaw,
+	NoteReadResponseRaw,
+	NoteWriteResponseRaw,
 	RawBranchInfo as SchemaRawBranchInfo,
 	RawCommitInfo as SchemaRawCommitInfo,
 	RawFileDiff as SchemaRawFileDiff,
 	RawFilteredFile as SchemaRawFilteredFile,
+	RawRepoBaseInfo as SchemaRawRepoBaseInfo,
+	RawRepoInfo as SchemaRawRepoInfo,
 } from './schemas';
 
 export interface OverrideableGitStorageOptions {
@@ -31,7 +36,7 @@ export interface GitStorageOptions extends OverrideableGitStorageOptions {
 export type ValidAPIVersion = 1;
 
 export interface GetRemoteURLOptions {
-	permissions?: ('git:write' | 'git:read' | 'repo:write')[];
+	permissions?: ('git:write' | 'git:read' | 'repo:write' | 'org:read')[];
 	ttl?: number;
 }
 
@@ -45,6 +50,10 @@ export interface Repo {
 	listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
 	listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
 	listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
+	getNote(options: GetNoteOptions): Promise<GetNoteResult>;
+	createNote(options: CreateNoteOptions): Promise<NoteWriteResult>;
+	appendNote(options: AppendNoteOptions): Promise<NoteWriteResult>;
+	deleteNote(options: DeleteNoteOptions): Promise<NoteWriteResult>;
 	getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResult>;
 	getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResult>;
 	grep(options: GrepOptions): Promise<GrepResult>;
@@ -84,6 +93,37 @@ export interface BaseRepo {
 	defaultBranch?: string;
 }
 
+export interface ListReposOptions extends GitStorageInvocationOptions {
+	cursor?: string;
+	limit?: number;
+}
+
+export type RawRepoBaseInfo = SchemaRawRepoBaseInfo;
+
+export interface RepoBaseInfo {
+	provider: string;
+	owner: string;
+	name: string;
+}
+
+export type RawRepoInfo = SchemaRawRepoInfo;
+
+export interface RepoInfo {
+	repoId: string;
+	url: string;
+	defaultBranch: string;
+	createdAt: string;
+	baseRepo?: RepoBaseInfo;
+}
+
+export type ListReposResponse = ListReposResponseRaw;
+
+export interface ListReposResult {
+	repos: RepoInfo[];
+	nextCursor?: string;
+	hasMore: boolean;
+}
+
 export interface CreateRepoOptions extends GitStorageInvocationOptions {
 	id?: string;
 	baseRepo?: BaseRepo;
@@ -192,6 +232,52 @@ export interface ListCommitsResult {
 	hasMore: boolean;
 }
 
+// Git notes API types
+export interface GetNoteOptions extends GitStorageInvocationOptions {
+	sha: string;
+}
+
+export type GetNoteResponse = NoteReadResponseRaw;
+
+export interface GetNoteResult {
+	sha: string;
+	note: string;
+	refSha: string;
+}
+
+interface NoteWriteBaseOptions extends GitStorageInvocationOptions {
+	sha: string;
+	note: string;
+	expectedRefSha?: string;
+	author?: CommitSignature;
+}
+
+export type CreateNoteOptions = NoteWriteBaseOptions;
+
+export type AppendNoteOptions = NoteWriteBaseOptions;
+
+export interface DeleteNoteOptions extends GitStorageInvocationOptions {
+	sha: string;
+	expectedRefSha?: string;
+	author?: CommitSignature;
+}
+
+export interface NoteWriteResultPayload {
+	success: boolean;
+	status: string;
+	message?: string;
+}
+
+export type NoteWriteResponse = NoteWriteResponseRaw;
+
+export interface NoteWriteResult {
+	sha: string;
+	targetRef: string;
+	baseCommit?: string;
+	newRefSha: string;
+	result: NoteWriteResultPayload;
+}
+
 // Branch Diff API types
 export interface GetBranchDiffOptions extends GitStorageInvocationOptions {
 	branch: string;