# Phorge SDK symbols > Complete symbol reference for the Phorge JavaScript SDK. Complete reference for the public exports of the `phorge` JavaScript package. See the [guide](https://phorge.net/docs) for a complete setup example. ## Contents - [Exports](https://phorge.net/docs/symbols#exports) - [GitStorage](https://phorge.net/docs/symbols#git-storage) - [Repository](https://phorge.net/docs/symbols#repository) - [CommitBuilder](https://phorge.net/docs/symbols#commit-builder) - [Authentication](https://phorge.net/docs/symbols#authentication) - [PhorgeError](https://phorge.net/docs/symbols#errors) - [Types](https://phorge.net/docs/symbols#types) ## Exports Runtime exports: `GitStorage`, `Repository`, `CommitBuilder`, `PhorgeError`, and `customerTokenProvider`. All types on this page are exported from the same package root. ## GitStorage The namespace-level client. ### `new GitStorage(options: GitStorageOptions)` Creates a client for one namespace. It reads the supplied private key locally and signs a short-lived token for each request. ### `createRepo(options: CreateRepoOptions): Promise` Creates a repository or returns the existing repository with that ID. The operation is idempotent. ### `repo(id: string): Repository` Creates a local handle for an existing repository without making a request. ### `listRepos(options?: PageOptions): Promise>` Lists repositories in the namespace. Pass the returned `next_cursor` into the next call while `has_more` is true. ## Repository Returned by `GitStorage.createRepo` and `GitStorage.repo`. Its public properties are `data: RepoData`, `id: string`, and `name: string`. ### `getRemoteURL(options?: RemoteURLOptions): Promise` Returns a credentialed HTTPS Git URL. The default scope is read-only and the default credential lifetime is 900 seconds. Treat the URL as a secret until it expires. ### `clone(destination: string, options?: CloneOptions): Promise` Runs a stock Git clone. Defaults to depth `1` and filter `blob:none`. Progress is delivered through `onProgress` when supplied. ### `createCommit(options: CreateCommitOptions): CommitBuilder` Starts a fluent file-operation commit. Add files or deletions, then call `send`. ### `sendCommit(input: CreateCommitRequest): Promise` Low-level form of the file-operation commit call. Upsert content is sent as raw multipart data. Prefer `createCommit` for normal use. ### `createCommitFromDiff(input: ApplyDiffInput): Promise` Applies a unified diff and creates its commit in one request. `expectedHeadSha` is required. ### `delete(): Promise` Permanently deletes the repository and its Git history. ### `listFiles(options?: ListFilesOptions): Promise>` Lists files at a branch, tag, or commit. Traversal is recursive unless `recursive` is false. Set `metadata` to include each path's latest commit. ### `getFileStream(path: string, options?: FileStreamOptions): Promise` Returns a Node.js readable stream for one file. Use `range` for a single HTTP byte range such as `bytes=0-1023`. ### `getFileURL(path: string, options?: FileURLOptions): Promise` Returns a short-lived browser URL that displays one file from a private repository as plain text. The credential is restricted to the selected repository, path, and ref, grants no write access, defaults to 600 seconds, and cannot exceed one hour. Treat the URL as a secret until it expires. ### `getArchiveStream(options?: ArchiveOptions): Promise` Returns a Node.js readable stream containing a tar.gz archive of a repository or path. ### `listCommits(options?: ListCommitsOptions): Promise>` Lists commits from the selected ref, which defaults to `HEAD`. ### `getCommit(sha: string): Promise` Returns one commit by SHA or other accepted revision. ### `getCommitDiff(sha: string): Promise` Returns the binary-capable unified patch for one commit. ### `getBranchDiff(base: string, head: string): Promise` Returns the three-dot diff from `base` to `head`. ### `grep(query: string, options?: GrepOptions): Promise>` Searches repository content. Context may be from 0 through 20 lines. ### `blame(path: string, options?: BlameOptions): Promise` Returns line-porcelain blame output for a file. ### `listBranches(options?: PageOptions): Promise>` Lists branches in name order. ### `createBranch(input: CreateBranchInput): Promise` Creates a branch when `expectedHeadSha` matches the resolved start point. ### `deleteBranch(name: string, expectedHeadSha: string): Promise` Deletes a branch only when its current SHA matches. ### `previewMerge(input: MergeInput): Promise` Checks a merge without moving the target branch. ### `merge(input: MergeInput): Promise` Merges the source into the target if the expected target head still matches. ### `createTag(input: TagInput): Promise` Creates a lightweight tag, or an annotated tag when `message` is present. ### `deleteTag(name: string, expectedHeadSha: string): Promise` Deletes a tag only when its current ref SHA matches. ## CommitBuilder Obtain a builder from `Repository.createCommit`. A builder can be sent once and must contain at least one operation. ### `addFileFromString(path: string, content: string, options?: AddFileOptions): this` Adds or replaces a UTF-8 file. ### `addFile(path: string, content: Buffer | Uint8Array, options?: AddFileOptions): this` Adds or replaces a binary file. ### `deletePath(path: string): this` Deletes a path in the new commit. ### `send(): Promise` Sends all operations in one atomic commit request. ## Authentication ### `customerTokenProvider(options: CustomerTokenOptions): TokenProvider` Creates the local JWT signer used by `GitStorage`. It accepts a P-256 EC or RSA private key. Optional `actor` becomes an `actor` claim for request auditing. When omitted, the claim is absent. The default lifetime is 900 seconds. ## PhorgeError ### `new PhorgeError(status: number, code: string, message: string, details?: Record)` Thrown for non-success HTTP responses. Public properties are `status`, `code`, `message`, and optional `details`. ## Types - `AddFileOptions`: `{ mode?: FileMode }` - `ApplyDiffInput`: `{ branch: string; expectedHeadSha: string; message: string; diff: string; author?: CommitIdentity; committer?: CommitIdentity }` - `ArchiveOptions`: `{ ref?: string; path?: string }` - `BlameOptions`: `{ ref?: string }` - `BlameResult`: `{ porcelain: string }` - `BranchData`: `{ name: string; sha: string; date: string; message: string }` - `CloneOptions`: Extends `RemoteURLOptions` with `depth?`, `filter?`, `gitBinary?`, `signal?`, and `onProgress?`. - `CommitData`: `{ sha: string; parents: string[]; author: string; date: string; message: string }` - `CommitIdentity`: `{ name: string; email: string }` - `CommitResult`: `{ commitSha: string; ref: string }` - `CreateBranchInput`: `{ name: string; startPoint: string; expectedHeadSha: string }` - `CreateCommitOptions`: `{ targetBranch: string; commitMessage: string; expectedHeadSha?: string; author?: CommitIdentity; committer?: CommitIdentity }`. The author is also the committer unless `committer` is supplied. - `CreateCommitRequest`: `{ branch: string; expectedHeadSha?: string; message: string; author?: CommitIdentity; committer?: CommitIdentity; operations: FileOperation[] }` - `CreateRepoOptions`: `{ id: string; ttlSeconds?: number; private?: boolean }`. Omitted or zero `ttlSeconds` means no scheduled deletion. Private repositories are the default. - `CustomerTokenOptions`: `{ key: string | Buffer | KeyObject; actor?: string; defaultTtlSeconds?: number }` - `FileCommit`: `{ sha: string; date: string; author: string; message: string }` - `FileEntry`: `{ path: string; mode: string; type: string; sha: string; size: number | null; last_commit?: FileCommit }` - `FileMode`: `"100644" | "100755" | "120000"` - `FileOperation`: `{ operation: "upsert"; path: string; content: Uint8Array; mode?: FileMode } | { operation: "delete"; path: string }` - `FileStreamOptions`: `{ ref?: string; range?: string }` - `FileURLOptions`: `{ ref?: string; ttl?: number; ttlSeconds?: number }`. The default lifetime is 600 seconds and the maximum is 3600 seconds. - `GitStorageOptions`: `{ name: string; key: string | Buffer | KeyObject; actor?: string; tokenTtlSeconds?: number; fetch?: typeof globalThis.fetch }` - `GrepMatch`: `{ path: string; line: number; text: string }` - `GrepOptions`: Extends `PageOptions` with `ref?` and `context?`. - `ListCommitsOptions`: Extends `PageOptions` with `ref?`. - `ListFilesOptions`: Extends `PageOptions` with `ref?`, `path?`, `recursive?`, and `metadata?`. - `MergeInput`: `{ source: string; target: string; expectedHeadSha: string; mode?: "fast-forward-only" | "fast-forward-preferred"; message?: string; author?: CommitIdentity; committer?: CommitIdentity }` - `MergePreviewResult`: `{ fast_forward: boolean; mergeable: boolean; result_sha: string; target_sha: string; source_sha: string }` - `Page`: `{ items: T[]; next_cursor: string; has_more: boolean }` - `PageOptions`: `{ cursor?: string; limit?: number }` - `RefResult`: `{ sha: string; ref: string }` - `RemoteURLOptions`: `{ scope?: "read" | "write"; ttl?: number; ttlSeconds?: number; operations?: string[]; refPolicies?: string[] }` - `RepoData`: `{ id: string; name: string; namespace: string; private: boolean; expires_at: string | null; size_bytes: number; content_version: number; git_url: string; api_url: string }`. `expires_at` is null when no deletion is scheduled. - `TagInput`: `{ name: string; target: string; expectedHeadSha: string; message?: string; tagger?: CommitIdentity }` - `TokenProvider`: `(request: TokenRequest) => Promise | string` - `TokenRequest`: `{ namespace: string; repo: string; scopes: TokenScope[]; ttlSeconds: number; operations?: string[]; refPolicies?: string[]; filePath?: string; ref?: string }` - `TokenScope`: `"file:read" | "git:read" | "git:write" | "repo:write" | "repo:delete" | "org:read"` --- [Back to contents](https://phorge.net/docs/symbols#contents) --- [Home](https://phorge.net/) · [Platform](https://platform.phorge.net/) · [Docs](https://phorge.net/docs) · [HTTP API](https://phorge.net/docs/http) · [SDK](https://github.com/sf-tools/phorge) · [Status](https://phorge.net/health)