@pierre/storage 0.0.5 → 0.0.7

package/src/index.ts

@@ -5,7 +5,11 @@
  */
 
 import { importPKCS8, SignJWT } from 'jose';
+import snakecaseKeys from 'snakecase-keys';
+import { ApiFetcher } from './fetch';
 import type {
+	CreateRepoOptions,
+	FindOneOptions,
 	GetBranchDiffOptions,
 	GetBranchDiffResponse,
 	GetCommitDiffOptions,
@@ -14,60 +18,56 @@ import type {
 	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;
-}
-
-export interface GetRemoteURLOptions {
-	permissions?: ('git:write' | 'git:read' | 'repo:write')[];
-	ttl?: number;
-}
-
-// Repo interface is now imported from types.ts
-
-export interface FindOneOptions {
-	id: string;
-}
-
-export interface CreateRepoOptions {
-	id?: string;
-}
-
-export interface CreateRepoResponse {
-	repo_id: string;
-	url: string;
-}
-
 // Import additional types from types.ts
 export * from './types';
 
+// Export webhook validation utilities
+export { parseSignatureHeader, validateWebhook, validateWebhookSignature } from './webhook';
+
 /**
  * Git Storage API
  */
-declare const __API_BASE_URL__: string;
+
 declare const __STORAGE_BASE_URL__: string;
+declare const __API_BASE_URL__: string;
 
 const API_BASE_URL = __API_BASE_URL__;
 const STORAGE_BASE_URL = __STORAGE_BASE_URL__;
+const API_VERSION: ValidAPIVersion = 1;
+
+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}`)!;
+}
 
 /**
  * Implementation of the Repo interface
  */
 class RepoImpl implements Repo {
+	private readonly api: ApiFetcher;
+
 	constructor(
 		public readonly id: string,
 		private readonly options: GitStorageOptions,
@@ -75,10 +75,16 @@ class RepoImpl implements Repo {
 			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 url = new URL(`https://${this.options.name}.${STORAGE_BASE_URL}/${this.id}.git`);
+		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();
@@ -87,25 +93,18 @@ class RepoImpl implements Repo {
 	async getFile(options: GetFileOptions): Promise<GetFileResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/file`);
-		url.searchParams.set('path', options.path);
+		const params: Record<string, string> = {
+			path: options.path,
+		};
+
 		if (options.ref) {
-			url.searchParams.set('ref', options.ref);
+			params.ref = options.ref;
 		}
 
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
-
-		if (!response.ok) {
-			throw new Error(`Failed to get file: ${response.statusText}`);
-		}
+		const response = await this.api.get({ path: 'repos/file', params }, jwt);
 
 		return (await response.json()) as GetFileResponse;
 	}
@@ -113,24 +112,13 @@ class RepoImpl implements Repo {
 	async listFiles(options?: ListFilesOptions): Promise<ListFilesResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
-		});
-
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/files`);
-		if (options?.ref) {
-			url.searchParams.set('ref', options.ref);
-		}
-
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		if (!response.ok) {
-			throw new Error(`Failed to list files: ${response.statusText}`);
-		}
+		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;
 	}
@@ -138,58 +126,48 @@ class RepoImpl implements Repo {
 	async listBranches(options?: ListBranchesOptions): Promise<ListBranchesResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/branches`);
-		if (options?.cursor) {
-			url.searchParams.set('cursor', options.cursor);
-		}
-		if (options?.limit) {
-			url.searchParams.set('limit', options.limit.toString());
-		}
-
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
+		let params: Record<string, string> | undefined;
 
-		if (!response.ok) {
-			throw new Error(`Failed to list branches: ${response.statusText}`);
+		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: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/commits`);
-		if (options?.branch) {
-			url.searchParams.set('branch', options.branch);
-		}
-		if (options?.cursor) {
-			url.searchParams.set('cursor', options.cursor);
-		}
-		if (options?.limit) {
-			url.searchParams.set('limit', options.limit.toString());
+		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 fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
-
-		if (!response.ok) {
-			throw new Error(`Failed to list commits: ${response.statusText}`);
-		}
+		const response = await this.api.get({ path: 'repos/commits', params }, jwt);
 
 		return (await response.json()) as ListCommitsResponse;
 	}
@@ -197,25 +175,18 @@ class RepoImpl implements Repo {
 	async getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/branches/diff`);
-		url.searchParams.set('branch', options.branch);
+		const params: Record<string, string> = {
+			branch: options.branch,
+		};
+
 		if (options.base) {
-			url.searchParams.set('base', options.base);
+			params.base = options.base;
 		}
 
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
-
-		if (!response.ok) {
-			throw new Error(`Failed to get branch diff: ${response.statusText}`);
-		}
+		const response = await this.api.get({ path: 'repos/branches/diff', params }, jwt);
 
 		return (await response.json()) as GetBranchDiffResponse;
 	}
@@ -223,22 +194,14 @@ class RepoImpl implements Repo {
 	async getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/api/v1/repos/diff`);
-		url.searchParams.set('sha', options.sha);
-
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
-		});
+		const params: Record<string, string> = {
+			sha: options.sha,
+		};
 
-		if (!response.ok) {
-			throw new Error(`Failed to get commit diff: ${response.statusText}`);
-		}
+		const response = await this.api.get({ path: 'repos/diff', params }, jwt);
 
 		return (await response.json()) as GetCommitDiffResponse;
 	}
@@ -246,30 +209,44 @@ class RepoImpl implements Repo {
 	async getCommit(options: GetCommitOptions): Promise<GetCommitResponse> {
 		const jwt = await this.generateJWT(this.id, {
 			permissions: ['git:read'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		const url = new URL(`${API_BASE_URL}/commit`);
-		url.searchParams.set('repo', this.id);
-		url.searchParams.set('sha', options.sha);
+		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;
+	}
 
-		const response = await fetch(url.toString(), {
-			method: 'GET',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
+	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
 		});
 
-		if (!response.ok) {
-			throw new Error(`Failed to get commit: ${response.statusText}`);
+		const body: Record<string, string> = {};
+
+		if (options.ref) {
+			body.ref = options.ref;
 		}
 
-		return (await response.json()) as GetCommitResponse;
+		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 (
@@ -292,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
@@ -307,18 +299,34 @@ export class GitStorage {
 
 		const jwt = await this.generateJWT(repoId, {
 			permissions: ['repo:write'],
-			ttl: 1 * 60 * 60, // 1hr in seconds
-		});
-
-		const response = await fetch(`${API_BASE_URL}/api/v1/repos`, {
-			method: 'POST',
-			headers: {
-				Authorization: `Bearer ${jwt}`,
-			},
+			ttl: options?.ttl ?? 1 * 60 * 60, // 1hr in seconds
 		});
 
-		if (!response.ok) {
-			throw new Error(`Failed to create repository: ${response.statusText}`);
+		const baseRepoOptions = options?.baseRepo
+			? {
+					provider: 'github',
+					...snakecaseKeys(options.baseRepo as unknown as Record<string, unknown>),
+				}
+			: null;
+
+		// Default defaultBranch to 'main' if not provided
+		const defaultBranch = options?.defaultBranch ?? 'main';
+
+		const createRepoPath =
+			baseRepoOptions || defaultBranch
+				? {
+						path: 'repos',
+						body: {
+							...(baseRepoOptions && { base_repo: baseRepoOptions }),
+							default_branch: defaultBranch,
+						},
+					}
+				: '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 new RepoImpl(repoId, this.options, this.generateJWT.bind(this));
@@ -330,6 +338,18 @@ export class GitStorage {
 	 * @returns The found repository
 	 */
 	async findOne(options: FindOneOptions): Promise<Repo | null> {
+		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;
@@ -24,12 +33,39 @@ export interface Repo {
 	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;
+	defaultBranch?: string;
 }
 
 export interface CreateRepoResponse {
@@ -38,7 +74,7 @@ export interface CreateRepoResponse {
 }
 
 // Get File API types
-export interface GetFileOptions {
+export interface GetFileOptions extends GitStorageInvocationOptions {
 	path: string;
 	ref?: string;
 }
@@ -51,8 +87,12 @@ export interface GetFileResponse {
 	is_binary: boolean;
 }
 
+export interface RepullOptions extends GitStorageInvocationOptions {
+	ref?: string;
+}
+
 // List Files API types
-export interface ListFilesOptions {
+export interface ListFilesOptions extends GitStorageInvocationOptions {
 	ref?: string;
 }
 
@@ -62,7 +102,7 @@ export interface ListFilesResponse {
 }
 
 // List Branches API types
-export interface ListBranchesOptions {
+export interface ListBranchesOptions extends GitStorageInvocationOptions {
 	cursor?: string;
 	limit?: number;
 }
@@ -81,7 +121,7 @@ export interface ListBranchesResponse {
 }
 
 // List Commits API types
-export interface ListCommitsOptions {
+export interface ListCommitsOptions extends GitStorageInvocationOptions {
 	branch?: string;
 	cursor?: string;
 	limit?: number;
@@ -104,7 +144,7 @@ export interface ListCommitsResponse {
 }
 
 // Branch Diff API types
-export interface GetBranchDiffOptions {
+export interface GetBranchDiffOptions extends GitStorageInvocationOptions {
 	branch: string;
 	base?: string;
 }
@@ -118,7 +158,7 @@ export interface GetBranchDiffResponse {
 }
 
 // Commit Diff API types
-export interface GetCommitDiffOptions {
+export interface GetCommitDiffOptions extends GitStorageInvocationOptions {
 	sha: string;
 }
 
@@ -155,7 +195,7 @@ export interface FilteredFile {
 }
 
 // Get Commit API types
-export interface GetCommitOptions {
+export interface GetCommitOptions extends GitStorageInvocationOptions {
 	sha: string;
 }
 
@@ -177,3 +217,51 @@ export interface GetCommitResponse {
 		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;
+}