@jetci/sdk

Baseline workflow author SDK for JETCI.

Workflow files import this package when they only need the core JETCI CI capabilities. Provider SDKs, such as a future @jetci/github-sdk, should re-export this package and add provider-specific events or job APIs on top.

Baseline Usage

import {onPush, defineJob} from "@jetci/sdk"

const test = defineJob(
  "Test",
  {runsOn: "ubuntu-latest"},
  async ctx => {
    await ctx.run("pnpm test")
  },
)

onPush({fromBranches: ["*"], toBranches: ["main"]}, async () => {
  await test({})
})

Extending Events

Provider SDKs should use createSdkScope() from @jetci/sdk/extend to define new event emitters and jobs with a provider origin. All event emitters share the same base structure: workflow code passes serializable event params plus an async event handler.

import {createSdkScope} from "@jetci/sdk/extend"

const GitHubSDK = createSdkScope("@jetci/github-sdk")

export const onPush = GitHubSDK.createEventEmitter<{
  fromBranches: string[]
  toBranches: string[]
}>("push")
export const defineJob = GitHubSDK.defineJob
export const onPullRequest = GitHubSDK.createEventEmitter<{
  branches: string[]
  actions?: Array<"opened" | "synchronize" | "closed">
}>("github.pull_request")

The provider SDK is the author-facing package. It should not need a provider-specific runtime shim. During discovery, @jetci/ir bundles the provider SDK and aliases trusted @jetci/sdk extension imports to @jetci/runtime-shim. Registrations are tagged with the scope origin, and IR only accepts origins allowed by the active host.

Secrets

Event registrations may declare the secrets their orchestrator needs. The host sees these declarations during discovery and is responsible for resolving them before the event handler runs.

onPush(
  {fromBranches: ["*"], toBranches: ["main"]},
  {secrets: ["NPM_TOKEN"]},
  async ctx => {
    const token = ctx.secrets?.NPM_TOKEN
  },
)

Secrets belong to event/orchestrator context. Jobs do not have a separate secrets API; pass only the values a job should receive through normal job params.

Exports

• @jetci/sdk: baseline onPush and defineJob APIs.
• @jetci/sdk/extend: createSdkScope, createEventEmitter, event helper types, and job helpers for provider SDKs.
• @jetci/sdk/registrar: stable registrar contract for hosts and provider SDK bridges. Workflow code should not import this directly; @jetci/ir enforces that during bundling.

Build

pnpm --dir packages/sdk build