@usine/github/github-app

Classes

AppAuthenticationError

The App private key cannot sign. Raised once, when the App layer is built.

Extends

• Schema.Class

Constructors

Constructor

new AppAuthenticationError(…args): AppAuthenticationError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

AppAuthenticationError

Properties

message

readonly message: string

---

AppCredentials

The App credentials the orchestrator keeps and never passes to a worker.

Extends

• Schema.Class

Constructors

Constructor

new AppCredentials(…args): AppCredentials

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

AppCredentials

Properties

appId

readonly appId: number & Brand<"GitHubAppId">

privateKey

readonly privateKey: Redacted<string & Brand<"GitHubAppPrivateKey">>

---

AppPermissionError

The installation lacks required repository grants; missing entries use name:level form.

Extends

• Schema.Class

Constructors

Constructor

new AppPermissionError(…args): AppPermissionError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

AppPermissionError

Properties

message

readonly message: string

missing

readonly missing: readonly string[]

---

CoveredProject

A registered repository covered by the discovered GitHub App installation.

Extends

• Schema.Class

Constructors

Constructor

new CoveredProject(…args): CoveredProject

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

CoveredProject

Properties

installationId

readonly installationId: number & Brand<"GitHubInstallationId">

repository

readonly repository: string & Brand<"RepositoryName">

repositoryId

readonly repositoryId: number & Brand<"GitHubRepositoryId">

---

GitHubApiError

A failed GitHub request, with an HTTP status when a response was received.

Extends

• Schema.Class

Constructors

Constructor

new GitHubApiError(…args): GitHubApiError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

GitHubApiError

Properties

message

readonly message: string

operation

readonly operation: "create-repository-label" | "discover-installation" | "fetch-item-labels" | "fetch-issue-snapshot" | "fetch-pull-request-snapshot" | "list-installation-repositories" | "list-repository-labels" | "mint-installation-token" | "mint-worker-token" | "poll-repository-changes" | "update-item-labels"

status

readonly status: Option<number>

---

GitHubApp

The factory’s GitHub identity and repository access. Orchestrator operations share installation-wide access; each Worker token is newly minted for the repository assigned to its Attempt.

Extends

• Context.ServiceClass

Properties

Service

readonly Service: object

The service’s operations: what yield* GitHubApp returns.

installation

readonly installation: () => Effect.Effect<Installation, GitHubAppError>

Returns the App installation after checking its required permissions.

Returns

Effect.Effect<Installation, GitHubAppError>

installationToken

readonly installationToken: () => Effect.Effect<InstallationToken, GitHubAppError>

Returns the shared installation-wide token for orchestrator operations, renewing it near expiry.

Returns

Effect.Effect<InstallationToken, GitHubAppError>

projectAccess

readonly projectAccess: (registry) => Effect.Effect<ReadonlyArray<ProjectAccess>, GitHubAppError>

Reports access for every registry repository, retaining uncovered Projects as individual errors.

Parameters

Parameter	Type
registry	ReadonlyArray<RepositoryName>

Returns

Effect.Effect<ReadonlyArray<ProjectAccess>, GitHubAppError>

workerToken

readonly workerToken: (project) => Effect.Effect<InstallationToken, GitHubAppError>

Mints a fresh token restricted to the covered Project’s repository for a Worker.

Parameters

Parameter	Type
project	CoveredProject

Returns

Effect.Effect<InstallationToken, GitHubAppError>

layer

readonly static layer: Layer<GitHubApp, AppAuthenticationError, HttpClient | GitHubCredentials>

---

GitHubCredentials

Supplies AppCredentials, so where credentials come from stays separate from how the App uses them.

Extends

• Context.ServiceClass

Properties

Service

readonly Service: AppCredentials

The service’s operations: what yield* GitHubCredentials returns.

---

GitHubRateLimitError

GitHub deferred the request until retryAt; callers can schedule a later attempt.

Extends

• Schema.Class

Constructors

Constructor

new GitHubRateLimitError(…args): GitHubRateLimitError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

GitHubRateLimitError

Properties

message

readonly message: string

operation

readonly operation: "create-repository-label" | "discover-installation" | "fetch-item-labels" | "fetch-issue-snapshot" | "fetch-pull-request-snapshot" | "list-installation-repositories" | "list-repository-labels" | "mint-installation-token" | "mint-worker-token" | "poll-repository-changes" | "update-item-labels"

retryAt

readonly retryAt: Utc

---

Installation

The discovered App installation and the account that owns it.

Extends

• Schema.Class

Constructors

Constructor

new Installation(…args): Installation

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

Installation

Properties

accountLogin

readonly accountLogin: string

id

readonly id: number & Brand<"GitHubInstallationId">

---

InstallationDiscoveryError

The App has no unambiguous active installation to use for repository access.

Extends

• Schema.Class

Constructors

Constructor

new InstallationDiscoveryError(…args): InstallationDiscoveryError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

InstallationDiscoveryError

Properties

message

readonly message: string

reason

readonly reason: "missing" | "multiple" | "suspended"

---

InstallationToken

A redacted installation credential with its expiry and permitted repository scope.

Extends

• Schema.Class

Constructors

Constructor

new InstallationToken(…args): InstallationToken

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

InstallationToken

Properties

expiresAt

readonly expiresAt: Utc

scope

readonly scope: InstallationWide | SingleRepository

value

readonly value: Redacted<string>

---

InstallationWide

Token access to every repository covered by the installation.

Extends

• Schema.Class

Constructors

Constructor

new InstallationWide(…args): InstallationWide

Parameters

Parameter	Type
…args	[props?: object, options?: MakeOptions]

Returns

InstallationWide

---

InvalidGitHubResponseError

GitHub returned a response that cannot be decoded or is missing required content.

Extends

• Schema.Class

Constructors

Constructor

new InvalidGitHubResponseError(…args): InvalidGitHubResponseError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

InvalidGitHubResponseError

Properties

detail

readonly detail: string

What made the response invalid: the decode path, the missing field, or the GraphQL errors.

message

readonly message: string

operation

readonly operation: "create-repository-label" | "discover-installation" | "fetch-item-labels" | "fetch-issue-snapshot" | "fetch-pull-request-snapshot" | "list-installation-repositories" | "list-repository-labels" | "mint-installation-token" | "mint-worker-token" | "poll-repository-changes" | "update-item-labels"

---

ProjectNotInstalledError

A registry repository the installation does not cover. Raised per project, so covered siblings still load.

Extends

• Schema.Class

Constructors

Constructor

new ProjectNotInstalledError(…args): ProjectNotInstalledError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

ProjectNotInstalledError

Properties

message

readonly message: string

repository

readonly repository: string & Brand<"RepositoryName">

---

SingleRepository

Token access restricted to the repository assigned to one Attempt.

Extends

• Schema.Class

Constructors

Constructor

new SingleRepository(…args): SingleRepository

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

SingleRepository

Properties

repository

readonly repository: string & Brand<"RepositoryName">

repositoryId

readonly repositoryId: number & Brand<"GitHubRepositoryId">

Interfaces

InstalledRepository

A repository reported by GitHub for an installation, identified by its numeric id and full name.

Properties

id

readonly id: number & Brand<"GitHubRepositoryId">

name

readonly name: string & Brand<"RepositoryName">

Type Aliases

AppId

AppId = typeof AppId.Type

The numeric GitHub App identity included in signed App JWTs.

---

GitHubAppError

GitHubAppError = typeof GitHubAppError.Type

Failures from discovering installation access or making an authenticated GitHub request.

---

GitHubOperation

GitHubOperation = typeof GitHubOperation.Type

The GitHub request that failed, shared by API, rate-limit, and response errors.

---

InstallationDiscoveryReason

InstallationDiscoveryReason = typeof InstallationDiscoveryReason.Type

Why App installation discovery could not select one usable installation.

---

InstallationId

InstallationId = typeof InstallationId.Type

The numeric identity of an installation of the factory’s GitHub App.

---

PrivateKey

PrivateKey = typeof PrivateKey.Type

A PEM-encoded RSA private key used to authenticate the GitHub App.

---

ProjectAccess

ProjectAccess = typeof ProjectAccess.Type

The installation coverage result for one registered repository.

---

RepositoryId

RepositoryId = typeof RepositoryId.Type

GitHub’s numeric repository identity, used to restrict installation tokens.

---

RequiredRepositoryPermission

RequiredRepositoryPermission = keyof typeof REQUIRED_REPOSITORY_PERMISSIONS

---

TokenScope

TokenScope = typeof TokenScope.Type

The repository coverage requested when minting an installation token.

Variables

AppId

const AppId: Schema.brand<Schema.Int, "GitHubAppId">

The numeric GitHub App identity included in signed App JWTs.

---

deriveProjectAccess

const deriveProjectAccess: (installation, registry, installed) => ReadonlyArray<ProjectAccess>

Checks each registry repository against the installation’s repositories and returns one ProjectAccess per project.

Parameters

Parameter	Type
installation	Installation
registry	ReadonlyArray<RepositoryName>
installed	ReadonlyArray<InstalledRepository>

Returns

ReadonlyArray<ProjectAccess>

---

GitHubAppError

const GitHubAppError: Schema.Union<readonly [typeof InstallationDiscoveryError, typeof AppPermissionError, typeof GitHubApiError, typeof GitHubRateLimitError, typeof InvalidGitHubResponseError]>

Failures from discovering installation access or making an authenticated GitHub request.

---

GitHubOperation

const GitHubOperation: Schema.Literals<readonly ["create-repository-label", "discover-installation", "fetch-item-labels", "fetch-issue-snapshot", "fetch-pull-request-snapshot", "list-installation-repositories", "list-repository-labels", "mint-installation-token", "mint-worker-token", "poll-repository-changes", "update-item-labels"]>

The GitHub request that failed, shared by API, rate-limit, and response errors.

---

InstallationDiscoveryReason

const InstallationDiscoveryReason: Schema.Literals<readonly ["missing", "multiple", "suspended"]>

Why App installation discovery could not select one usable installation.

---

InstallationId

const InstallationId: Schema.brand<Schema.Int, "GitHubInstallationId">

The numeric identity of an installation of the factory’s GitHub App.

---

missingPermissions

const missingPermissions: (granted) => ReadonlyArray<string>

The required repository permissions an installation grant does not satisfy, as name:level strings.

Parameters

Parameter	Type
granted	Readonly<Record<string, string>>

Returns

ReadonlyArray<string>

---

PrivateKey

const PrivateKey: Schema.brand<Schema.NonEmptyString, "GitHubAppPrivateKey">

A PEM-encoded RSA private key used to authenticate the GitHub App.

---

ProjectAccess

const ProjectAccess: Schema.Union<readonly [typeof CoveredProject, typeof ProjectNotInstalledError]>

The installation coverage result for one registered repository.

---

RedactedPrivateKey

const RedactedPrivateKey: Schema.RedactedFromValue<Schema.brand<Schema.NonEmptyString, "GitHubAppPrivateKey">>

An App signing key that stays redacted in diagnostics and cannot be encoded.

---

RepositoryId

const RepositoryId: Schema.brand<Schema.Int, "GitHubRepositoryId">

GitHub’s numeric repository identity, used to restrict installation tokens.

---

REQUIRED_REPOSITORY_PERMISSIONS

const REQUIRED_REPOSITORY_PERMISSIONS: object

Repository grants required for polling, label updates, and agent-authored changes.

Type Declaration

checks

readonly checks: "read"

contents

readonly contents: "write"

issues

readonly issues: "write"

metadata

readonly metadata: "read"

pull_requests

readonly pull_requests: "write"

---

TokenScope

const TokenScope: Schema.Union<readonly [typeof InstallationWide, typeof SingleRepository]>

The repository coverage requested when minting an installation token.