@pierre/storage 0.0.11 → 0.1.0

package/README.md

@@ -123,31 +123,50 @@ console.log(commitDiff.files);
 
 // Create a commit using the streaming helper
 const fs = await import('node:fs/promises');
-const response = await repo
+const result = await repo
   .createCommit({
     targetRef: 'refs/heads/main',
     commitMessage: 'Update docs',
+    author: { name: 'Docs Bot', email: 'docs@example.com' },
   })
   .addFileFromString('docs/changelog.md', '# v2.0.1\n- add streaming SDK\n')
   .addFile('docs/readme.md', await fs.readFile('README.md'))
   .deletePath('docs/legacy.txt')
   .send();
 
-console.log(response.commit.commit_sha);
-console.log(response.result.new_sha);
-console.log(response.result.old_sha); // 40 hex chars; all zeroes for brand-new branches
+console.log(result.commitSha);
+console.log(result.refUpdate.newSha);
+console.log(result.refUpdate.oldSha); // All zeroes when the ref is created
 ```
 
 The builder exposes:
 
-- `addFile(path, source, options)` to attach bytes, async iterables, readable streams, or buffers.
-- `addFileFromString(path, contents, options)` for UTF-8 text helpers.
+- `addFile(path, source, options)` to attach bytes from strings, typed arrays, ArrayBuffers, `Blob`
+  or `File` objects, `ReadableStream`s, or iterable/async-iterable sources.
+- `addFileFromString(path, contents, options)` for text helpers (defaults to UTF-8 and accepts any
+  Node.js `BufferEncoding`).
 - `deletePath(path)` to remove files or folders.
 - `send()` to finalize the commit and receive metadata about the new commit.
 
-`send()` resolves to `{ commit, result }`. The `result` payload mirrors the HTTP response, including
-`old_sha` (always a 40-character hex string; it is all zeroes when the target ref is being created),
-`new_sha`, `status`, and an optional `message`.
+`send()` resolves to an object with the new commit metadata plus the ref update:
+
+```ts
+type CommitResult = {
+  commitSha: string;
+  treeSha: string;
+  targetRef: string;
+  packBytes: number;
+  blobCount: number;
+  refUpdate: {
+    ref: string;
+    oldSha: string; // All zeroes when the ref is created
+    newSha: string;
+  };
+};
+```
+
+If the backend reports a failure (for example, the branch advanced past `baseRef`) the builder
+throws a `RefUpdateError` containing the status, reason, and ref details.
 
 **Options**
 
@@ -156,35 +175,16 @@ The builder exposes:
 - `baseRef` (optional): Branch or commit that must match the remote tip; omit to fast-forward
   unconditionally.
 - `commitMessage` (required): The commit message.
-- `author` and `committer` (optional): Include `name`, `email`, and optional ISO 8601 `date`.
+- `author` (required): Include `name` and `email` for the commit author.
+- `committer` (optional): Include `name` and `email`. If omitted, the author identity is reused.
 - `signal` (optional): Abort an in-flight upload with `AbortController`.
 
 > Files are chunked into 4 MiB segments under the hood, so you can stream large assets without
 > buffering them entirely in memory. File paths are normalized relative to the repository root.
 
-### Creating a new branch
-
-You can create and populate a new branch in a single request by pointing `targetRef` at the new ref
-and setting `baseRef` to the branch (or commit SHA) you want to fork from.
-
-```typescript
-const baseBranch = 'main';
-const featureBranch = 'refs/heads/feature/onboarding';
-
-await repo
-  .createCommit({
-    targetRef: featureBranch,
-    baseRef: `refs/heads/${baseBranch}`,
-    commitMessage: 'feat: add onboarding copy',
-  })
-  .addFileFromString('apps/dashboard/Onboarding.tsx', '<Onboarding />\n')
-  .send();
-```
-
-> If you omit `baseRef` while referencing a brand-new `targetRef`, the service creates an orphan
-> commit with no parent. The new branch starts from an empty tree, so only the files you include in
-> this commit will exist. Always provide `baseRef` when you need the branch to inherit history or
-> files from another branch.
+> The `targetRef` must already exist on the remote repository. To seed an empty repository, point to
+> the default branch and omit `baseRef`; the service will create the first commit only when no refs
+> are present.
 
 ### Streaming Large Files
 
@@ -199,6 +199,7 @@ await repo
     targetRef: 'refs/heads/assets',
     baseRef: 'refs/heads/main',
     commitMessage: 'Upload latest design bundle',
+    author: { name: 'Assets Uploader', email: 'assets@example.com' },
   })
   .addFile('assets/design-kit.zip', createReadStream('/tmp/design-kit.zip'))
   .send();
@@ -223,6 +224,7 @@ class GitStorage {
 interface GitStorageOptions {
   name: string; // Your identifier
   key: string; // Your API key
+  defaultTTL?: number; // Default TTL for generated JWTs (seconds)
 }
 
 interface CreateRepoOptions {
@@ -238,11 +240,11 @@ interface Repo {
   getRemoteURL(options?: GetRemoteURLOptions): Promise<string>;
 
   getFileStream(options: GetFileOptions): Promise<Response>;
-  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>;
+  listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
+  listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
+  listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
+  getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResult>;
+  getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResult>;
 }
 
 interface GetRemoteURLOptions {
@@ -254,12 +256,14 @@ interface GetRemoteURLOptions {
 interface GetFileOptions {
   path: string;
   ref?: string; // Branch, tag, or commit SHA
+  ttl?: number;
 }
 
 // getFileStream() returns a standard Fetch Response for streaming bytes
 
 interface ListFilesOptions {
   ref?: string; // Branch, tag, or commit SHA
+  ttl?: number;
 }
 
 interface ListFilesResponse {
@@ -267,53 +271,75 @@ interface ListFilesResponse {
   ref: string; // The resolved reference
 }
 
+interface ListFilesResult {
+  paths: string[];
+  ref: string;
+}
+
 interface ListBranchesOptions {
   cursor?: string;
   limit?: number;
+  ttl?: number;
 }
 
 interface ListBranchesResponse {
   branches: BranchInfo[];
-  next_cursor?: string;
-  has_more: boolean;
+  nextCursor?: string;
+  hasMore: boolean;
+}
+
+interface ListBranchesResult {
+  branches: BranchInfo[];
+  nextCursor?: string;
+  hasMore: boolean;
 }
 
 interface BranchInfo {
   cursor: string;
   name: string;
-  head_sha: string;
-  created_at: string;
+  headSha: string;
+  createdAt: string;
 }
 
 interface ListCommitsOptions {
   branch?: string;
   cursor?: string;
   limit?: number;
+  ttl?: number;
 }
 
 interface ListCommitsResponse {
   commits: CommitInfo[];
-  next_cursor?: string;
-  has_more: boolean;
+  nextCursor?: string;
+  hasMore: boolean;
+}
+
+interface ListCommitsResult {
+  commits: CommitInfo[];
+  nextCursor?: string;
+  hasMore: boolean;
 }
 
 interface CommitInfo {
   sha: string;
   message: string;
-  author_name: string;
-  author_email: string;
-  committer_name: string;
-  committer_email: string;
-  date: string;
+  authorName: string;
+  authorEmail: string;
+  committerName: string;
+  committerEmail: string;
+  date: Date;
+  rawDate: string;
 }
 
 interface GetBranchDiffOptions {
   branch: string;
   base?: string; // Defaults to 'main'
+  ttl?: number;
 }
 
 interface GetCommitDiffOptions {
   sha: string;
+  ttl?: number;
 }
 
 interface GetBranchDiffResponse {
@@ -321,16 +347,30 @@ interface GetBranchDiffResponse {
   base: string;
   stats: DiffStats;
   files: FileDiff[];
-  filtered_files: FilteredFile[];
+  filteredFiles: FilteredFile[];
+}
+
+interface GetBranchDiffResult {
+  branch: string;
+  base: string;
+  stats: DiffStats;
+  files: FileDiff[];
+  filteredFiles: FilteredFile[];
 }
 
 interface GetCommitDiffResponse {
   sha: string;
   stats: DiffStats;
   files: FileDiff[];
-  filtered_files: FilteredFile[];
+  filteredFiles: FilteredFile[];
 }
 
+interface GetCommitDiffResult {
+  sha: string;
+  stats: DiffStats;
+  files: FileDiff[];
+  filteredFiles: FilteredFile[];
+}
 interface DiffStats {
   files: number;
   additions: number;
@@ -338,21 +378,78 @@ interface DiffStats {
   changes: number;
 }
 
+type DiffFileState =
+  | 'added'
+  | 'modified'
+  | 'deleted'
+  | 'renamed'
+  | 'copied'
+  | 'type_changed'
+  | 'unmerged'
+  | 'unknown';
+
+interface DiffFileBase {
+  path: string;
+  state: DiffFileState;
+  rawState: string;
+  oldPath?: string;
+  bytes: number;
+  isEof: boolean;
+}
+
 interface FileDiff {
   path: string;
-  state: string;
-  old_path?: string;
+  state: DiffFileState;
+  rawState: string;
+  oldPath?: string;
   bytes: number;
-  is_eof: boolean;
-  diff: string;
+  isEof: boolean;
+  raw: string;
 }
 
 interface FilteredFile {
   path: string;
-  state: string;
-  old_path?: string;
+  state: DiffFileState;
+  rawState: string;
+  oldPath?: string;
   bytes: number;
-  is_eof: boolean;
+  isEof: boolean;
+}
+
+interface RefUpdate {
+  ref: string;
+  oldSha: string;
+  newSha: string;
+}
+
+interface CommitResult {
+  commitSha: string;
+  treeSha: string;
+  targetRef: string;
+  packBytes: number;
+  blobCount: number;
+  refUpdate: RefUpdate;
+}
+
+interface ResetCommitOptions {
+  targetBranch: string;
+  targetCommitSha: string;
+  commitMessage?: string;
+  expectedHeadSha?: string;
+  author: CommitSignature;
+  committer?: CommitSignature;
+}
+
+interface ResetCommitResult {
+  commitSha: string;
+  treeSha: string;
+  targetBranch: string;
+  packBytes: number;
+  refUpdate: {
+    branch: string;
+    oldSha: string;
+    newSha: string;
+  };
 }
 ```
 
@@ -383,28 +480,12 @@ try {
 } catch (error) {
   // Error: GitStorage key must be a non-empty string.
 }
+-
 ```
 
-## Development
-
-This package is part of the Pierre monorepo. To work on it locally:
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the package
-moon git-storage-sdk:build
-
-# Run tests
-moon git-storage-sdk:test
-
-# Run in watch mode
-moon git-storage-sdk:dev
-
-# Format code
-moon git-storage-sdk:format-write
-```
+- Mutating operations (commit builder, `resetCommit`) throw `RefUpdateError` when the backend
+  reports a ref failure. Inspect `error.status`, `error.reason`, `error.message`, and
+  `error.refUpdate` for details.
 
 ## License