Phorge SDK symbols

Complete reference for the public exports of the phorge JavaScript package. See the guide for a complete setup example.

Contents

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<Repository>

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<Page<RepoData>>

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<string>

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<void>

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<RefResult>

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<CommitResult>

Applies a unified diff and creates its commit in one request. expectedHeadSha is required.

delete(): Promise<void>

Permanently deletes the repository and its Git history.

listFiles(options?: ListFilesOptions): Promise<Page<FileEntry>>

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<Readable>

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<string>

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<Readable>

Returns a Node.js readable stream containing a tar.gz archive of a repository or path.

listCommits(options?: ListCommitsOptions): Promise<Page<CommitData>>

Lists commits from the selected ref, which defaults to HEAD.

getCommit(sha: string): Promise<CommitData>

Returns one commit by SHA or other accepted revision.

getCommitDiff(sha: string): Promise<string>

Returns the binary-capable unified patch for one commit.

getBranchDiff(base: string, head: string): Promise<string>

Returns the three-dot diff from base to head.

grep(query: string, options?: GrepOptions): Promise<Page<GrepMatch>>

Searches repository content. Context may be from 0 through 20 lines.

blame(path: string, options?: BlameOptions): Promise<BlameResult>

Returns line-porcelain blame output for a file.

listBranches(options?: PageOptions): Promise<Page<BranchData>>

Lists branches in name order.

createBranch(input: CreateBranchInput): Promise<RefResult>

Creates a branch when expectedHeadSha matches the resolved start point.

deleteBranch(name: string, expectedHeadSha: string): Promise<RefResult>

Deletes a branch only when its current SHA matches.

previewMerge(input: MergeInput): Promise<MergePreviewResult>

Checks a merge without moving the target branch.

merge(input: MergeInput): Promise<RefResult>

Merges the source into the target if the expected target head still matches.

createTag(input: TagInput): Promise<RefResult>

Creates a lightweight tag, or an annotated tag when message is present.

deleteTag(name: string, expectedHeadSha: string): Promise<RefResult>

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<CommitResult>

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<string, unknown>)

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<T>
{ 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> | 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