@pierre/storage 0.0.10 → 0.1.0

package/README.md

@@ -51,7 +51,7 @@ The SDK generates secure URLs with JWT authentication for Git operations:
 ```typescript
 // Get URL with default permissions (git:write, git:read) and 1-year TTL
 const url = await repo.getRemoteURL();
-// Returns: https://t:JWT@your-name.git.storage/repo-id.git
+// Returns: https://t:JWT@your-name.code.storage/repo-id.git
 
 // Configure the Git remote
 console.log(`Run: git remote add origin ${url}`);
@@ -120,6 +120,89 @@ const commitDiff = await repo.getCommitDiff({
 });
 console.log(commitDiff.stats);
 console.log(commitDiff.files);
+
+// Create a commit using the streaming helper
+const fs = await import('node:fs/promises');
+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(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 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 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**
+
+- `targetRef` (required): Fully qualified ref that will receive the commit (for example
+  `refs/heads/main`).
+- `baseRef` (optional): Branch or commit that must match the remote tip; omit to fast-forward
+  unconditionally.
+- `commitMessage` (required): The commit message.
+- `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.
+
+> 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
+
+The commit builder accepts any async iterable of bytes, so you can stream large assets without
+buffering:
+
+```typescript
+import { createReadStream } from 'node:fs';
+
+await repo
+  .createCommit({
+    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();
 ```
 
 ## API Reference
@@ -141,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 {
@@ -156,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 {
@@ -172,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 {
@@ -185,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 {
@@ -239,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;
@@ -256,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;
+  };
 }
 ```
 
@@ -301,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