@pierre/storage 1.0.3 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pierre/storage",
-	"version": "1.0.3",
+	"version": "1.2.0",
 	"description": "Pierre Git Storage SDK",
 	"license": "MIT",
 	"type": "module",

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   listBranchesResponseSchema,
   listCommitsResponseSchema,
   listFilesResponseSchema,
+  listFilesWithMetadataResponseSchema,
   listReposResponseSchema,
   noteReadResponseSchema,
   noteWriteResponseSchema,
@@ -36,6 +37,7 @@ import type {
   BranchInfo,
   CommitBuilder,
   CommitInfo,
+  CommitMetadata,
   CommitResult,
   CreateBranchOptions,
   CreateBranchResponse,
@@ -48,6 +50,7 @@ import type {
   DeleteRepoOptions,
   DeleteRepoResult,
   DiffFileState,
+  FileWithMetadata,
   FileDiff,
   FilteredFile,
   FindOneOptions,
@@ -74,16 +77,22 @@ import type {
   ListCommitsResult,
   ListFilesOptions,
   ListFilesResult,
+  ListFilesWithMetadataOptions,
+  ListFilesWithMetadataResponse,
+  ListFilesWithMetadataResult,
   ListReposOptions,
   ListReposResponse,
   ListReposResult,
   NoteWriteResult,
   PullUpstreamOptions,
   RawBranchInfo,
+  RawCommitMetadata,
   RawCommitInfo,
+  RawFileWithMetadata,
   RawFileDiff,
   RawFilteredFile,
   RefUpdate,
+  RepoOptions,
   Repo,
   RestoreCommitOptions,
   RestoreCommitResult,
@@ -310,6 +319,39 @@ function transformListCommitsResult(
   };
 }
 
+function transformFileWithMetadata(raw: RawFileWithMetadata): FileWithMetadata {
+  return {
+    path: raw.path,
+    mode: raw.mode,
+    size: raw.size,
+    lastCommitSha: raw.last_commit_sha,
+  };
+}
+
+function transformCommitMetadata(raw: RawCommitMetadata): CommitMetadata {
+  return {
+    author: raw.author,
+    date: new Date(raw.date),
+    rawDate: raw.date,
+    message: raw.message,
+  };
+}
+
+function transformListFilesWithMetadataResult(
+  raw: ListFilesWithMetadataResponse
+): ListFilesWithMetadataResult {
+  const commits: Record<string, CommitMetadata> = {};
+  for (const [sha, commit] of Object.entries(raw.commits)) {
+    commits[sha] = transformCommitMetadata(commit);
+  }
+
+  return {
+    files: raw.files.map(transformFileWithMetadata),
+    commits,
+    ref: raw.ref,
+  };
+}
+
 function normalizeDiffState(rawState: string): DiffFileState {
   if (!rawState) {
     return 'unknown';
@@ -675,6 +717,34 @@ class RepoImpl implements Repo {
     return { paths: raw.paths, ref: raw.ref };
   }
 
+  async listFilesWithMetadata(
+    options?: ListFilesWithMetadataOptions
+  ): Promise<ListFilesWithMetadataResult> {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ['git:read'],
+      ttl,
+    });
+
+    const params: Record<string, string> = {};
+    if (options?.ref) {
+      params.ref = options.ref;
+    }
+    if (typeof options?.ephemeral === 'boolean') {
+      params.ephemeral = String(options.ephemeral);
+    }
+    const response = await this.api.get(
+      {
+        path: 'repos/files/metadata',
+        params: Object.keys(params).length ? params : undefined,
+      },
+      jwt
+    );
+
+    const raw = listFilesWithMetadataResponseSchema.parse(await response.json());
+    return transformListFilesWithMetadataResult(raw);
+  }
+
   async listBranches(
     options?: ListBranchesOptions
   ): Promise<ListBranchesResult> {
@@ -1393,13 +1463,11 @@ export class GitStorage {
       throw new Error('Repository already exists');
     }
 
-    return new RepoImpl(
-      repoId,
-      resolvedDefaultBranch ?? 'main',
-      new Date().toISOString(),
-      this.options,
-      this.generateJWT.bind(this)
-    );
+    return this.repo({
+      id: repoId,
+      defaultBranch: resolvedDefaultBranch ?? 'main',
+      createdAt: new Date().toISOString(),
+    });
   }
 
   /**
@@ -1448,13 +1516,33 @@ export class GitStorage {
     if (resp.status === 404) {
       return null;
     }
-    const body = (await resp.json()) as { default_branch?: string; created_at?: string };
+
+    const body = (await resp.json()) as {
+      default_branch?: string;
+      created_at?: string;
+    };
     const defaultBranch = body.default_branch ?? 'main';
     const createdAt = body.created_at ?? '';
-    return new RepoImpl(
-      options.id,
+
+    return this.repo({
+      id: options.id,
       defaultBranch,
       createdAt,
+    });
+  }
+
+  /**
+   * Create a Repo handle from known metadata without making an HTTP request.
+   */
+  repo(options: RepoOptions): Repo {
+    if (!options || typeof options.id !== 'string' || options.id.trim() === '') {
+      throw new Error('repo requires a non-empty repository id.');
+    }
+
+    return new RepoImpl(
+      options.id,
+      options.defaultBranch ?? 'main',
+      options.createdAt ?? '',
       this.options,
       this.generateJWT.bind(this)
     );

package/src/schemas.ts

@@ -5,6 +5,25 @@ export const listFilesResponseSchema = z.object({
   ref: z.string(),
 });
 
+export const fileWithMetadataRawSchema = z.object({
+  path: z.string(),
+  mode: z.string(),
+  size: z.number(),
+  last_commit_sha: z.string(),
+});
+
+export const commitMetadataRawSchema = z.object({
+  author: z.string(),
+  date: z.string(),
+  message: z.string(),
+});
+
+export const listFilesWithMetadataResponseSchema = z.object({
+  files: z.array(fileWithMetadataRawSchema),
+  commits: z.record(commitMetadataRawSchema),
+  ref: z.string(),
+});
+
 export const branchInfoSchema = z.object({
   cursor: z.string(),
   name: z.string(),
@@ -202,6 +221,11 @@ export const errorEnvelopeSchema = z.object({
 });
 
 export type ListFilesResponseRaw = z.infer<typeof listFilesResponseSchema>;
+export type RawFileWithMetadata = z.infer<typeof fileWithMetadataRawSchema>;
+export type RawCommitMetadata = z.infer<typeof commitMetadataRawSchema>;
+export type ListFilesWithMetadataResponseRaw = z.infer<
+  typeof listFilesWithMetadataResponseSchema
+>;
 export type RawBranchInfo = z.infer<typeof branchInfoSchema>;
 export type ListBranchesResponseRaw = z.infer<
   typeof listBranchesResponseSchema

package/src/types.ts

@@ -8,11 +8,14 @@ import type {
   ListBranchesResponseRaw,
   ListCommitsResponseRaw,
   ListFilesResponseRaw,
+  ListFilesWithMetadataResponseRaw,
   ListReposResponseRaw,
   NoteReadResponseRaw,
   NoteWriteResponseRaw,
   RawBranchInfo as SchemaRawBranchInfo,
+  RawCommitMetadata as SchemaRawCommitMetadata,
   RawCommitInfo as SchemaRawCommitInfo,
+  RawFileWithMetadata as SchemaRawFileWithMetadata,
   RawFileDiff as SchemaRawFileDiff,
   RawFilteredFile as SchemaRawFilteredFile,
   RawRepoBaseInfo as SchemaRawRepoBaseInfo,
@@ -49,6 +52,9 @@ export interface Repo {
   getFileStream(options: GetFileOptions): Promise<Response>;
   getArchiveStream(options?: ArchiveOptions): Promise<Response>;
   listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
+  listFilesWithMetadata(
+    options?: ListFilesWithMetadataOptions
+  ): Promise<ListFilesWithMetadataResult>;
   listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
   listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
   getNote(options: GetNoteOptions): Promise<GetNoteResult>;
@@ -84,6 +90,12 @@ export interface FindOneOptions {
   id: string;
 }
 
+export interface RepoOptions {
+  id: string;
+  defaultBranch?: string;
+  createdAt?: string;
+}
+
 export type SupportedRepoProvider = 'github';
 
 export interface PublicGitHubBaseRepoAuth {
@@ -190,6 +202,37 @@ export interface ListFilesResult {
   ref: string;
 }
 
+export interface ListFilesWithMetadataOptions extends GitStorageInvocationOptions {
+  ref?: string;
+  ephemeral?: boolean;
+}
+
+export type RawFileWithMetadata = SchemaRawFileWithMetadata;
+
+export interface FileWithMetadata {
+  path: string;
+  mode: string;
+  size: number;
+  lastCommitSha: string;
+}
+
+export type RawCommitMetadata = SchemaRawCommitMetadata;
+
+export interface CommitMetadata {
+  author: string;
+  date: Date;
+  rawDate: string;
+  message: string;
+}
+
+export type ListFilesWithMetadataResponse = ListFilesWithMetadataResponseRaw;
+
+export interface ListFilesWithMetadataResult {
+  files: FileWithMetadata[];
+  commits: Record<string, CommitMetadata>;
+  ref: string;
+}
+
 // List Branches API types
 export interface ListBranchesOptions extends GitStorageInvocationOptions {
   cursor?: string;