@pierre/storage 0.0.3 → 0.0.6

package/src/fetch.ts

@@ -0,0 +1,71 @@
+import type { ValidAPIVersion, ValidMethod, ValidPath } from './types';
+
+interface RequestOptions {
+	allowedStatus?: number[];
+}
+
+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}`;
+	}
+
+	private getRequestUrl(path: ValidPath) {
+		if (typeof path === 'string') {
+			return `${this.getBaseUrl()}/${path}`;
+		} else if (path.params) {
+			const paramStr = new URLSearchParams(path.params).toString();
+			return `${this.getBaseUrl()}/${path.path}${paramStr ? `?${paramStr}` : ''}`;
+		} else {
+			return `${this.getBaseUrl()}/${path.path}`;
+		}
+	}
+
+	private async fetch(path: ValidPath, method: ValidMethod, jwt: string, options?: RequestOptions) {
+		const requestUrl = this.getRequestUrl(path);
+
+		const requestOptions: RequestInit = {
+			method,
+			headers: {
+				Authorization: `Bearer ${jwt}`,
+				'Content-Type': 'application/json',
+			},
+		};
+
+		if (method !== 'GET' && typeof path !== 'string' && path.body) {
+			requestOptions.body = JSON.stringify(path.body);
+		}
+
+		const response = await fetch(requestUrl, requestOptions);
+
+		if (!response.ok) {
+			const allowed = options?.allowedStatus ?? [];
+			if (!allowed.includes(response.status)) {
+				throw new Error(`Failed to fetch ${method} ${requestUrl}: ${response.statusText}`);
+			}
+		}
+		return response;
+	}
+
+	async get(path: ValidPath, jwt: string, options?: RequestOptions) {
+		return this.fetch(path, 'GET', jwt, options);
+	}
+
+	async post(path: ValidPath, jwt: string, options?: RequestOptions) {
+		return this.fetch(path, 'POST', jwt, options);
+	}
+
+	async put(path: ValidPath, jwt: string, options?: RequestOptions) {
+		return this.fetch(path, 'PUT', jwt, options);
+	}
+
+	async delete(path: ValidPath, jwt: string, options?: RequestOptions) {
+		return this.fetch(path, 'DELETE', jwt, options);
+	}
+}

package/src/index.ts

@@ -5,50 +5,248 @@
  */
 
 import { importPKCS8, SignJWT } from 'jose';
+import snakecaseKeys from 'snakecase-keys';
+import { ApiFetcher } from './fetch';
+import type {
+	CreateRepoOptions,
+	FindOneOptions,
+	GetBranchDiffOptions,
+	GetBranchDiffResponse,
+	GetCommitDiffOptions,
+	GetCommitDiffResponse,
+	GetCommitOptions,
+	GetCommitResponse,
+	GetFileOptions,
+	GetFileResponse,
+	GetRemoteURLOptions,
+	GitStorageOptions,
+	ListBranchesOptions,
+	ListBranchesResponse,
+	ListCommitsOptions,
+	ListCommitsResponse,
+	ListFilesOptions,
+	ListFilesResponse,
+	OverrideableGitStorageOptions,
+	Repo,
+	RepullOptions,
+	ValidAPIVersion,
+} from './types';
 
 /**
  * Type definitions for Pierre Git Storage SDK
  */
 
-export interface GitStorageOptions {
-	key: string;
-	name: string;
-}
+// Import additional types from types.ts
+export * from './types';
 
-export interface GetRemoteURLOptions {
-	permissions?: ('git:write' | 'git:read' | 'repo:write')[];
-	ttl?: number;
-}
+// Export webhook validation utilities
+export { parseSignatureHeader, validateWebhook, validateWebhookSignature } from './webhook';
 
-export interface Repo {
-	id: string;
-	getRemoteURL(options?: GetRemoteURLOptions): Promise<string>;
-}
+/**
+ * Git Storage API
+ */
 
-export interface FindOneOptions {
-	id: string;
-}
+declare const __STORAGE_BASE_URL__: string;
+declare const __API_BASE_URL__: string;
 
-export interface CreateRepoOptions {
-	id?: string;
-}
+const API_BASE_URL = __API_BASE_URL__;
+const STORAGE_BASE_URL = __STORAGE_BASE_URL__;
+const API_VERSION: ValidAPIVersion = 1;
 
-export interface CreateRepoResponse {
-	repo_id: string;
-	url: string;
+const apiInstanceMap = new Map<string, ApiFetcher>();
+
+function getApiInstance(baseUrl: string, version: ValidAPIVersion) {
+	if (!apiInstanceMap.has(`${baseUrl}--${version}`)) {
+		apiInstanceMap.set(`${baseUrl}--${version}`, new ApiFetcher(baseUrl, version));
+	}
+	return apiInstanceMap.get(`${baseUrl}--${version}`)!;
 }
 
 /**
- * Git Storage API
+ * Implementation of the Repo interface
  */
-declare const __API_BASE_URL__: string;
-declare const __STORAGE_BASE_URL__: string;
+class RepoImpl implements Repo {
+	private readonly api: ApiFetcher;
 
-const API_BASE_URL = __API_BASE_URL__;
-const STORAGE_BASE_URL = __STORAGE_BASE_URL__;
+	constructor(
+		public readonly id: string,
+		private readonly options: GitStorageOptions,
+		private readonly generateJWT: (
+			repoId: string,
+			options?: GetRemoteURLOptions,
+		) => Promise<string>,
+	) {
+		this.api = getApiInstance(
+			this.options.apiBaseUrl ?? API_BASE_URL,
+			this.options.apiVersion ?? API_VERSION,
+		);
+	}
+
+	async getRemoteURL(urlOptions?: GetRemoteURLOptions): Promise<string> {
+		const storageBaseUrl = this.options.storageBaseUrl ?? STORAGE_BASE_URL;
+		const url = new URL(`https://${this.options.name}.${storageBaseUrl}/${this.id}.git`);
+		url.username = `t`;
+		url.password = await this.generateJWT(this.id, urlOptions);
+		return url.toString();
+	}
+
+	async getFile(options: GetFileOptions): Promise<GetFileResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const params: Record<string, string> = {
+			path: options.path,
+		};
+
+		if (options.ref) {
+			params.ref = options.ref;
+		}
+
+		const response = await this.api.get({ path: 'repos/file', params }, jwt);
+
+		return (await response.json()) as GetFileResponse;
+	}
+
+	async listFiles(options?: ListFilesOptions): Promise<ListFilesResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const params: Record<string, string> | undefined = options?.ref
+			? { ref: options.ref }
+			: undefined;
+		const response = await this.api.get({ path: 'repos/files', params }, jwt);
+
+		return (await response.json()) as ListFilesResponse;
+	}
+
+	async listBranches(options?: ListBranchesOptions): Promise<ListBranchesResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		let params: Record<string, string> | undefined;
+
+		if (options?.cursor || !options?.limit) {
+			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/branches', params }, jwt);
+
+		return (await response.json()) as ListBranchesResponse;
+	}
+
+	async listCommits(options?: ListCommitsOptions): Promise<ListCommitsResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		let params: Record<string, string> | undefined;
+
+		if (options?.branch || options?.cursor || options?.limit) {
+			params = {};
+			if (options?.branch) {
+				params.branch = options.branch;
+			}
+			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/commits', params }, jwt);
+
+		return (await response.json()) as ListCommitsResponse;
+	}
+
+	async getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const params: Record<string, string> = {
+			branch: options.branch,
+		};
+
+		if (options.base) {
+			params.base = options.base;
+		}
+
+		const response = await this.api.get({ path: 'repos/branches/diff', params }, jwt);
+
+		return (await response.json()) as GetBranchDiffResponse;
+	}
+
+	async getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const params: Record<string, string> = {
+			sha: options.sha,
+		};
+
+		const response = await this.api.get({ path: 'repos/diff', params }, jwt);
+
+		return (await response.json()) as GetCommitDiffResponse;
+	}
+
+	async getCommit(options: GetCommitOptions): Promise<GetCommitResponse> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:read'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const params: Record<string, string> = {
+			repo: this.id,
+			sha: options.sha,
+		};
+		const response = await this.api.get({ path: 'commit', params }, jwt);
+
+		return (await response.json()) as GetCommitResponse;
+	}
+
+	async repull(options: RepullOptions): Promise<void> {
+		const jwt = await this.generateJWT(this.id, {
+			permissions: ['git:write'],
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
+		});
+
+		const body: Record<string, string> = {};
+
+		if (options.ref) {
+			body.ref = options.ref;
+		}
+
+		const response = await this.api.post({ path: 'repos/repull', body }, jwt);
+
+		if (response.status !== 202) {
+			throw new Error(`Repull failed: ${response.status} ${await response.text()}`);
+		}
+
+		return;
+	}
+}
 
 export class GitStorage {
+	private static overrides: OverrideableGitStorageOptions = {};
 	private options: GitStorageOptions;
+	private api: ApiFetcher;
 
 	constructor(options: GitStorageOptions) {
 		if (
@@ -71,12 +269,27 @@ export class GitStorage {
 			throw new Error('GitStorage key must be a non-empty string.');
 		}
 
+		const resolvedApiBaseUrl =
+			options.apiBaseUrl ?? GitStorage.overrides.apiBaseUrl ?? API_BASE_URL;
+		const resolvedApiVersion = options.apiVersion ?? GitStorage.overrides.apiVersion ?? API_VERSION;
+		const resolvedStorageBaseUrl =
+			options.storageBaseUrl ?? GitStorage.overrides.storageBaseUrl ?? STORAGE_BASE_URL;
+
+		this.api = getApiInstance(resolvedApiBaseUrl, resolvedApiVersion);
+
 		this.options = {
 			key: options.key,
 			name: options.name,
+			apiBaseUrl: resolvedApiBaseUrl,
+			apiVersion: resolvedApiVersion,
+			storageBaseUrl: resolvedStorageBaseUrl,
 		};
 	}
 
+	static override(options: OverrideableGitStorageOptions): void {
+		this.overrides = Object.assign({}, this.overrides, options);
+	}
+
 	/**
 	 * Create a new repository
 	 * @returns The created repository
@@ -86,29 +299,32 @@ export class GitStorage {
 
 		const jwt = await this.generateJWT(repoId, {
 			permissions: ['repo:write'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const response = await fetch(`${API_BASE_URL}/api/v1/repos`, {
-			method: 'POST',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
+		const baseRepoOptions = options?.baseRepo
+			? {
+					provider: 'github',
+					...snakecaseKeys(options.baseRepo as unknown as Record<string, unknown>),
+				}
+			: null;
 
-		if (!response.ok) {
-			throw new Error(`Failed to create repository: ${response.statusText}`);
+		const createRepoPath = baseRepoOptions
+			? {
+					path: 'repos',
+					body: {
+						base_repo: baseRepoOptions,
+					},
+				}
+			: 'repos';
+
+		// Allow 409 so we can map it to a clearer error message
+		const resp = await this.api.post(createRepoPath, jwt, { allowedStatus: [409] });
+		if (resp.status === 409) {
+			throw new Error('Repository already exists');
 		}
 
-		return {
-			id: repoId,
-			getRemoteURL: async (urlOptions?: GetRemoteURLOptions): Promise<string> => {
-				const url = new URL(`https://${this.options.name}.${STORAGE_BASE_URL}/${repoId}.git`);
-				url.username = `t`;
-				url.password = await this.generateJWT(repoId, urlOptions);
-				return url.toString();
-			},
-		};
+		return new RepoImpl(repoId, this.options, this.generateJWT.bind(this));
 	}
 
 	/**
@@ -117,15 +333,19 @@ export class GitStorage {
 	 * @returns The found repository
 	 */
 	async findOne(options: FindOneOptions): Promise<Repo | null> {
-		return {
-			id: options.id,
-			getRemoteURL: async (urlOptions?: GetRemoteURLOptions): Promise<string> => {
-				const url = new URL(`https://${this.options.name}.${STORAGE_BASE_URL}/${options.id}.git`);
-				url.username = `t`;
-				url.password = await this.generateJWT(options.id, urlOptions);
-				return url.toString();
-			},
-		};
+		const jwt = await this.generateJWT(options.id, {
+			permissions: ['git:read'],
+			ttl: 1 * 60 * 60,
+		});
+
+		// Allow 404 to indicate "not found" without throwing
+		const resp = await this.api.get('repo', jwt, { allowedStatus: [404] });
+		if (resp.status === 404) {
+			return null;
+		}
+		// On 200, we could validate response, but RepoImpl only needs the repo URL/id
+		// const body = await resp.json(); // not required for now
+		return new RepoImpl(options.id, this.options, this.generateJWT.bind(this));
 	}
 
 	/**

package/src/types.ts

@@ -2,11 +2,20 @@
  * Type definitions for Pierre Git Storage SDK
  */
 
-export interface GitStorageOptions {
+export interface OverrideableGitStorageOptions {
+	apiBaseUrl?: string;
+	storageBaseUrl?: string;
+	apiVersion?: ValidAPIVersion;
+}
+
+export interface GitStorageOptions extends OverrideableGitStorageOptions {
 	key: string;
 	name: string;
+	defaultTTL?: number;
 }
 
+export type ValidAPIVersion = 1;
+
 export interface GetRemoteURLOptions {
 	permissions?: ('git:write' | 'git:read' | 'repo:write')[];
 	ttl?: number;
@@ -15,17 +24,243 @@ export interface GetRemoteURLOptions {
 export interface Repo {
 	id: string;
 	getRemoteURL(options?: GetRemoteURLOptions): Promise<string>;
+	getFile(options: GetFileOptions): Promise<GetFileResponse>;
+	listFiles(options?: ListFilesOptions): Promise<ListFilesResponse>;
+	listBranches(options?: ListBranchesOptions): Promise<ListBranchesResponse>;
+	listCommits(options?: ListCommitsOptions): Promise<ListCommitsResponse>;
+	getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResponse>;
+	getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResponse>;
+	getCommit(options: GetCommitOptions): Promise<GetCommitResponse>;
+}
+
+export type ValidMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type SimplePath = string;
+type ComplexPath = {
+	path: string;
+	params?: Record<string, string>;
+	body?: Record<string, any>;
+};
+export type ValidPath = SimplePath | ComplexPath;
+
+interface GitStorageInvocationOptions {
+	ttl?: number;
 }
 
 export interface FindOneOptions {
 	id: string;
 }
 
-export interface CreateRepoOptions {
+export type SupportedRepoProvider = 'github';
+
+export interface BaseRepo {
+	/**
+	 * @default github
+	 */
+	provider?: SupportedRepoProvider;
+	owner: string;
+	name: string;
+	defaultBranch?: string;
+}
+
+export interface CreateRepoOptions extends GitStorageInvocationOptions {
 	id?: string;
+	baseRepo?: BaseRepo;
 }
 
 export interface CreateRepoResponse {
 	repo_id: string;
 	url: string;
 }
+
+// Get File API types
+export interface GetFileOptions extends GitStorageInvocationOptions {
+	path: string;
+	ref?: string;
+}
+
+export interface GetFileResponse {
+	path: string;
+	ref: string;
+	content: string;
+	size: number;
+	is_binary: boolean;
+}
+
+export interface RepullOptions extends GitStorageInvocationOptions {
+	ref?: string;
+}
+
+// List Files API types
+export interface ListFilesOptions extends GitStorageInvocationOptions {
+	ref?: string;
+}
+
+export interface ListFilesResponse {
+	paths: string[];
+	ref: string;
+}
+
+// List Branches API types
+export interface ListBranchesOptions extends GitStorageInvocationOptions {
+	cursor?: string;
+	limit?: number;
+}
+
+export interface BranchInfo {
+	cursor: string;
+	name: string;
+	head_sha: string;
+	created_at: string;
+}
+
+export interface ListBranchesResponse {
+	branches: BranchInfo[];
+	next_cursor?: string;
+	has_more: boolean;
+}
+
+// List Commits API types
+export interface ListCommitsOptions extends GitStorageInvocationOptions {
+	branch?: string;
+	cursor?: string;
+	limit?: number;
+}
+
+export interface CommitInfo {
+	sha: string;
+	message: string;
+	author_name: string;
+	author_email: string;
+	committer_name: string;
+	committer_email: string;
+	date: string;
+}
+
+export interface ListCommitsResponse {
+	commits: CommitInfo[];
+	next_cursor?: string;
+	has_more: boolean;
+}
+
+// Branch Diff API types
+export interface GetBranchDiffOptions extends GitStorageInvocationOptions {
+	branch: string;
+	base?: string;
+}
+
+export interface GetBranchDiffResponse {
+	branch: string;
+	base: string;
+	stats: DiffStats;
+	files: FileDiff[];
+	filtered_files: FilteredFile[];
+}
+
+// Commit Diff API types
+export interface GetCommitDiffOptions extends GitStorageInvocationOptions {
+	sha: string;
+}
+
+export interface GetCommitDiffResponse {
+	sha: string;
+	stats: DiffStats;
+	files: FileDiff[];
+	filtered_files: FilteredFile[];
+}
+
+// Shared diff types
+export interface DiffStats {
+	files: number;
+	additions: number;
+	deletions: number;
+	changes: number;
+}
+
+export interface FileDiff {
+	path: string;
+	state: string;
+	old_path?: string;
+	bytes: number;
+	is_eof: boolean;
+	diff: string;
+}
+
+export interface FilteredFile {
+	path: string;
+	state: string;
+	old_path?: string;
+	bytes: number;
+	is_eof: boolean;
+}
+
+// Get Commit API types
+export interface GetCommitOptions extends GitStorageInvocationOptions {
+	sha: string;
+}
+
+export interface GetCommitResponse {
+	sha: string;
+	message: string;
+	author: {
+		name: string;
+		email: string;
+	};
+	committer: {
+		name: string;
+		email: string;
+	};
+	date: string;
+	stats: {
+		additions: number;
+		deletions: number;
+		total: number;
+	};
+}
+
+// Webhook types
+export interface WebhookValidationOptions {
+	/**
+	 * Maximum age of webhook in seconds (default: 300 seconds / 5 minutes)
+	 * Set to 0 to disable timestamp validation
+	 */
+	maxAgeSeconds?: number;
+}
+
+export interface WebhookValidationResult {
+	/**
+	 * Whether the webhook signature and timestamp are valid
+	 */
+	valid: boolean;
+	/**
+	 * Error message if validation failed
+	 */
+	error?: string;
+	/**
+	 * The parsed webhook event type (e.g., "push")
+	 */
+	eventType?: string;
+	/**
+	 * The timestamp from the signature (Unix seconds)
+	 */
+	timestamp?: number;
+}
+
+// Webhook event payloads
+export interface WebhookPushEvent {
+	repository: {
+		id: string;
+		url: string;
+	};
+	ref: string;
+	before: string;
+	after: string;
+	customer_id: string;
+	pushed_at: string; // RFC3339 timestamp
+}
+
+export type WebhookEventPayload = WebhookPushEvent;
+
+export interface ParsedWebhookSignature {
+	timestamp: string;
+	signature: string;
+}