Skip to content

public-api.md

Latest commit

 

History

History
93 lines (72 loc) · 2.88 KB

public-api.md

File metadata and controls

93 lines (72 loc) · 2.88 KB
Raw

Public API proposal

Stable API

  • Configuration — validated GitHub App credentials and User-Agent.
  • Environment — ordered lookup across getenv(), $_ENV, and $_SERVER.
  • Workflow — validated repository workflow coordinates and ref.
  • GitHubAppClient — creates JWTs, retrieves installation tokens, and dispatches workflows.
  • InstallationToken — sensitive token value plus immutable expiration time.
  • Exception classes under Exception.

Classes under Internal and exact log messages are implementation details.

Fully programmatic configuration

$configuration = new Configuration(
    appId: '12345',
    installationId: '67890',
    privateKey: $privateKeyPem,
    userAgent: 'acme-deployer/1.0',
);

$workflow = new Workflow('acme', 'website', 'deploy.yml', 'main');

Environment fallback and overrides

// The consuming application loads environment variables.
$configuration = Configuration::fromEnvironment([
    'user_agent' => 'acme-deployer/1.0', // Overrides GITHUB_USER_AGENT.
]);

$workflow = Workflow::fromEnvironment([
    'ref' => 'release', // Overrides GITHUB_WORKFLOW_REF.
]);

Lookup order is getenv(), then $_ENV, then $_SERVER. Explicit non-null values always win. Empty values fail validation rather than falling through silently.

Client construction and optional logger

use Fnet\GitHubDispatchWorkflow\GitHubAppClient;

$github = new GitHubAppClient(
    configuration: $configuration,
    httpClient: $psr18Client,
    requestFactory: $psr17RequestFactory,
    streamFactory: $psr17StreamFactory,
    logger: $psr3Logger, // Optional.
    clock: $psrClock,   // Optional.
);

JWT, installation token, and workflow dispatch

$jwt = $github->createJwt();

$installationToken = $github->createInstallationToken();
$token = $installationToken->value();
$expiresAt = $installationToken->expiresAt();

$github->dispatchWorkflow($workflow, [
    'app' => 'acme-portal',
    'environment' => 'production',
]);

dispatchWorkflow() obtains a fresh installation token, matching the existing no-cache behavior. Inputs are caller-defined; the package does not force LEM's application-specific app input.

Exception handling

use Fnet\GitHubDispatchWorkflow\Exception\AuthenticationException;
use Fnet\GitHubDispatchWorkflow\Exception\ConfigurationException;
use Fnet\GitHubDispatchWorkflow\Exception\TransportException;
use Fnet\GitHubDispatchWorkflow\Exception\WorkflowDispatchException;

try {
    $github->dispatchWorkflow($workflow, ['app' => 'acme']);
} catch (ConfigurationException $e) {
    // Correct local configuration.
} catch (AuthenticationException $e) {
    // Inspect statusCode() and requestId(); never log credentials.
} catch (WorkflowDispatchException $e) {
    // Inspect sanitized GitHub response context.
} catch (TransportException $e) {
    // Handle the injected client's transport failure.
}