elegantchaos/octoid

What It Includes

• GitHub payload models used by ActionStatus:

- Events / Event - Workflows / Workflow - WorkflowRuns / WorkflowRun - Supporting types (Actor, Author, Commit, etc.)

• Resource resolvers for key endpoints:

- EventsResource - WorkflowsResource - WorkflowResource

• Polling helpers built on JSONSession 3.x:

- Session.repositoryUpdates(...) - RepositoryReference - RepositoryPollConfiguration - RepositoryUpdate - MessageProcessor - UnchangedProcessor - MessageReceiver

Requirements

• Swift tools: 6.2
• Platforms:

- macOS 26+ - Mac Catalyst 26+ - iOS 26+ - tvOS 26+ - watchOS 11+

Installation

Add Octoid to your package dependencies:

dependencies: [
    .package(url: "https://github.com/elegantchaos/Octoid.git", from: "3.0.0")
]

Then add Octoid to the target dependencies that need it.

Quick Start

Create a JSONSession session and consume Octoid's repository update stream.

import Foundation
import Octoid
import JSONSession

let session = Session(
  base: URL(string: "https://api.github.com")!,
  token: githubToken
)
let stream = session.repositoryUpdates(
  for: RepositoryReference(owner: "elegantchaos", name: "Octoid"),
  configuration: RepositoryPollConfiguration(interval: .seconds(60))
)

for await update in stream {
  switch update {
  case .events(let events):
    print("events: \(events.count)")
  case .workflows(let workflows):
    print("workflows: \(workflows.total_count)")
  case .workflowRuns(let target, let runs):
    print("runs for \(target.name): \(runs.isEmpty ? "no runs" : "has runs")")
  case .message(_, let message):
    print("api message: \(message)")
  case .transportError(_, let description):
    print("transport error: \(description)")
  }
}

Workflow Runs

Use WorkflowResource in one of three modes:

1. By workflow name: WorkflowResource(name:owner:workflow:)
2. By workflow ID: WorkflowResource(name:owner:workflowID:)
3. All workflows: WorkflowResource.allWorkflows(name:owner:)

If workflow names are not stable, fetch WorkflowsResource first and use workflows.preferredWorkflow?.id.

Testing

See TESTING.md for local and integration test setup.

Package Metadata

Repository: elegantchaos/octoid

Default branch: main

README: README.md