@pierre/storage 0.0.3 → 0.0.6

package/dist/index.d.ts

@@ -1,15 +1,17 @@
-/**
- * Pierre Git Storage SDK
- *
- * A TypeScript SDK for interacting with Pierre's git storage system
- */
 /**
  * Type definitions for Pierre Git Storage SDK
  */
-interface GitStorageOptions {
+interface OverrideableGitStorageOptions {
+    apiBaseUrl?: string;
+    storageBaseUrl?: string;
+    apiVersion?: ValidAPIVersion;
+}
+interface GitStorageOptions extends OverrideableGitStorageOptions {
     key: string;
     name: string;
+    defaultTTL?: number;
 }
+type ValidAPIVersion = 1;
 interface GetRemoteURLOptions {
     permissions?: ('git:write' | 'git:read' | 'repo:write')[];
     ttl?: number;
@@ -17,20 +19,281 @@ interface GetRemoteURLOptions {
 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>;
+}
+type ValidMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type SimplePath = string;
+type ComplexPath = {
+    path: string;
+    params?: Record<string, string>;
+    body?: Record<string, any>;
+};
+type ValidPath = SimplePath | ComplexPath;
+interface GitStorageInvocationOptions {
+    ttl?: number;
 }
 interface FindOneOptions {
     id: string;
 }
-interface CreateRepoOptions {
+type SupportedRepoProvider = 'github';
+interface BaseRepo {
+    /**
+     * @default github
+     */
+    provider?: SupportedRepoProvider;
+    owner: string;
+    name: string;
+    defaultBranch?: string;
+}
+interface CreateRepoOptions extends GitStorageInvocationOptions {
     id?: string;
+    baseRepo?: BaseRepo;
 }
 interface CreateRepoResponse {
     repo_id: string;
     url: string;
 }
+interface GetFileOptions extends GitStorageInvocationOptions {
+    path: string;
+    ref?: string;
+}
+interface GetFileResponse {
+    path: string;
+    ref: string;
+    content: string;
+    size: number;
+    is_binary: boolean;
+}
+interface RepullOptions extends GitStorageInvocationOptions {
+    ref?: string;
+}
+interface ListFilesOptions extends GitStorageInvocationOptions {
+    ref?: string;
+}
+interface ListFilesResponse {
+    paths: string[];
+    ref: string;
+}
+interface ListBranchesOptions extends GitStorageInvocationOptions {
+    cursor?: string;
+    limit?: number;
+}
+interface BranchInfo {
+    cursor: string;
+    name: string;
+    head_sha: string;
+    created_at: string;
+}
+interface ListBranchesResponse {
+    branches: BranchInfo[];
+    next_cursor?: string;
+    has_more: boolean;
+}
+interface ListCommitsOptions extends GitStorageInvocationOptions {
+    branch?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface CommitInfo {
+    sha: string;
+    message: string;
+    author_name: string;
+    author_email: string;
+    committer_name: string;
+    committer_email: string;
+    date: string;
+}
+interface ListCommitsResponse {
+    commits: CommitInfo[];
+    next_cursor?: string;
+    has_more: boolean;
+}
+interface GetBranchDiffOptions extends GitStorageInvocationOptions {
+    branch: string;
+    base?: string;
+}
+interface GetBranchDiffResponse {
+    branch: string;
+    base: string;
+    stats: DiffStats;
+    files: FileDiff[];
+    filtered_files: FilteredFile[];
+}
+interface GetCommitDiffOptions extends GitStorageInvocationOptions {
+    sha: string;
+}
+interface GetCommitDiffResponse {
+    sha: string;
+    stats: DiffStats;
+    files: FileDiff[];
+    filtered_files: FilteredFile[];
+}
+interface DiffStats {
+    files: number;
+    additions: number;
+    deletions: number;
+    changes: number;
+}
+interface FileDiff {
+    path: string;
+    state: string;
+    old_path?: string;
+    bytes: number;
+    is_eof: boolean;
+    diff: string;
+}
+interface FilteredFile {
+    path: string;
+    state: string;
+    old_path?: string;
+    bytes: number;
+    is_eof: boolean;
+}
+interface GetCommitOptions extends GitStorageInvocationOptions {
+    sha: string;
+}
+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;
+    };
+}
+interface WebhookValidationOptions {
+    /**
+     * Maximum age of webhook in seconds (default: 300 seconds / 5 minutes)
+     * Set to 0 to disable timestamp validation
+     */
+    maxAgeSeconds?: number;
+}
+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;
+}
+interface WebhookPushEvent {
+    repository: {
+        id: string;
+        url: string;
+    };
+    ref: string;
+    before: string;
+    after: string;
+    customer_id: string;
+    pushed_at: string;
+}
+type WebhookEventPayload = WebhookPushEvent;
+interface ParsedWebhookSignature {
+    timestamp: string;
+    signature: string;
+}
+
+/**
+ * Webhook validation utilities for Pierre Git Storage
+ */
+
+/**
+ * Parse the X-Pierre-Signature header
+ * Format: t=<timestamp>,sha256=<signature>
+ */
+declare function parseSignatureHeader(header: string): ParsedWebhookSignature | null;
+/**
+ * Validate a webhook signature and timestamp
+ *
+ * @param payload - The raw webhook payload (request body)
+ * @param signatureHeader - The X-Pierre-Signature header value
+ * @param secret - The webhook secret for HMAC verification
+ * @param options - Validation options
+ * @returns Validation result with details
+ *
+ * @example
+ * ```typescript
+ * const result = await validateWebhookSignature(
+ *   requestBody,
+ *   request.headers['x-pierre-signature'],
+ *   webhookSecret
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error('Invalid webhook:', result.error);
+ *   return;
+ * }
+ * ```
+ */
+declare function validateWebhookSignature(payload: string | Buffer, signatureHeader: string, secret: string, options?: WebhookValidationOptions): Promise<WebhookValidationResult>;
+/**
+ * Validate a webhook request
+ *
+ * This is a convenience function that validates the signature and parses the payload.
+ *
+ * @param payload - The raw webhook payload (request body)
+ * @param headers - The request headers (must include x-pierre-signature and x-pierre-event)
+ * @param secret - The webhook secret for HMAC verification
+ * @param options - Validation options
+ * @returns The parsed webhook payload if valid, or validation error
+ *
+ * @example
+ * ```typescript
+ * const result = await validateWebhook(
+ *   request.body,
+ *   request.headers,
+ *   process.env.WEBHOOK_SECRET
+ * );
+ *
+ * if (!result.valid) {
+ *   return new Response('Invalid webhook', { status: 401 });
+ * }
+ *
+ * // Type-safe access to the webhook payload
+ * console.log('Push event:', result.payload);
+ * ```
+ */
+declare function validateWebhook(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: WebhookValidationOptions): Promise<WebhookValidationResult & {
+    payload?: WebhookEventPayload;
+}>;
+
+/**
+ * Pierre Git Storage SDK
+ *
+ * A TypeScript SDK for interacting with Pierre's git storage system
+ */
+
 declare class GitStorage {
+    private static overrides;
     private options;
+    private api;
     constructor(options: GitStorageOptions);
+    static override(options: OverrideableGitStorageOptions): void;
     /**
      * Create a new repository
      * @returns The created repository
@@ -56,4 +319,4 @@ declare class GitStorage {
 declare function createClient(options: GitStorageOptions): GitStorage;
 type StorageOptions = GitStorageOptions;
 
-export { type CreateRepoOptions, type CreateRepoResponse, type FindOneOptions, type GetRemoteURLOptions, GitStorage, type GitStorageOptions, type Repo, type StorageOptions, createClient };
+export { type BaseRepo, type BranchInfo, type CommitInfo, type CreateRepoOptions, type CreateRepoResponse, type DiffStats, type FileDiff, type FilteredFile, type FindOneOptions, type GetBranchDiffOptions, type GetBranchDiffResponse, type GetCommitDiffOptions, type GetCommitDiffResponse, type GetCommitOptions, type GetCommitResponse, type GetFileOptions, type GetFileResponse, type GetRemoteURLOptions, GitStorage, type GitStorageOptions, type ListBranchesOptions, type ListBranchesResponse, type ListCommitsOptions, type ListCommitsResponse, type ListFilesOptions, type ListFilesResponse, type OverrideableGitStorageOptions, type ParsedWebhookSignature, type Repo, type RepullOptions, type StorageOptions, type SupportedRepoProvider, type ValidAPIVersion, type ValidMethod, type ValidPath, type WebhookEventPayload, type WebhookPushEvent, type WebhookValidationOptions, type WebhookValidationResult, createClient, parseSignatureHeader, validateWebhook, validateWebhookSignature };