File API Updates

Code Storage has a larger file API update across the TypeScript, Python, and Go SDKs. The new methods and options make repository reads cheaper and more selective: clients can page through subtrees, revalidate cached files, request byte ranges, or fetch only headers instead of pulling full trees and file bodies over the network. That unlocks faster repository browsers, previews, indexers, cached file readers, and sync jobs, while making Code Storage behave more like an object store API built specifically for repos.

listFiles now supports subtree listing, non-recursive directory views, and cursor pagination. It still returns the legacy paths array, and now also returns structured entries with the path, entry type, and Git mode.

const page = await repo.listFiles({
  path: 'docs',
  recursive: false,
  limit: 100,
});

console.log(page.entries, page.nextCursor, page.hasMore);

listFilesWithMetadata has the same path and pagination controls. File rows can include the Git entry type, so callers can distinguish blobs, trees, symlinks, and submodules while still reading size, mode, and last-commit metadata.

page = await repo.list_files_with_metadata(
    path="src",
    limit=100,
)

print(page["files"][0].get("type"), page.get("next_cursor"), page["has_more"])

File reads now forward range and conditional headers. That means clients can request byte ranges, reuse cached content with ETags, and handle conditional responses without downloading the full file body.

const resp = await repo.getFileStream({
  path: 'README.md',
  headers: {
    range: 'bytes=0-1023',
    ifNoneMatch: '"abc123"',
  },
});

console.log(resp.status, resp.headers.get('content-range'), resp.headers.get('etag'));

There is also a new headFile method for inspecting file metadata without reading the body. It calls HEAD /repos/file and returns the HTTP status plus headers such as blob SHA, last commit SHA, content length, ETag, Last-Modified, Accept-Ranges, Content-Range, and Content-Type.

metadata, err := repo.HeadFile(ctx, storage.HeadFileOptions{
    Path: "README.md",
    Headers: storage.FileRequestHeaders{
        IfNoneMatch: `"abc123"`,
    },
})
if err != nil {
    return err
}

fmt.Println(metadata.StatusCode, metadata.ETag, metadata.LastCommitSHA)

Commit history can now be scoped to a path as well. Pass path to listCommits to return commits that touched a specific file or subtree.

const commits = await repo.listCommits({
  branch: 'main',
  path: 'docs/guide.md',
});

One smaller SDK compatibility update is included too: the TypeScript SDK now preserves the API's squash merge result label instead of converting it to merge_commit, matching Python and Go.

These updates are available through the SDKs and documented in the SDK reference pages for listFiles, listFilesWithMetadata, getFileStream, headFile, and listCommits.

See the docs