@effected/github 0.16.0 → 0.17.0

package/WorkflowDispatch.js

@@ -26,6 +26,24 @@ var WorkflowRunStatus = class extends Schema.Class("WorkflowRunStatus")({
 		return this.status === "completed";
 	}
 };
+/**
+* The run a `workflow_dispatch` created, as GitHub reports it when asked.
+*
+* @remarks
+* Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+* directly with {@link WorkflowDispatchShape.runStatus} and
+* {@link WorkflowDispatchShape.cancelRun}.
+*
+* @public
+*/
+var DispatchedRun = class extends Schema.Class("DispatchedRun")({
+	/** The created run's numeric id. */
+	runId: Schema.Int,
+	/** The run's API URL. */
+	runUrl: Schema.String,
+	/** The run's web URL. */
+	htmlUrl: Schema.String
+}) {};
 const DEFAULT_INTERVAL = Duration.seconds(10);
 const DEFAULT_TIMEOUT = Duration.minutes(5);
 /**
@@ -60,6 +78,7 @@ var WorkflowDispatch = class WorkflowDispatch extends Context.Service()("@effect
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
 		dispatch: overrides.dispatch ?? (() => unstubbed("dispatch")),
+		dispatchWithRun: overrides.dispatchWithRun ?? (() => unstubbed("dispatchWithRun")),
 		runStatus: overrides.runStatus ?? (() => unstubbed("runStatus")),
 		cancelRun: overrides.cancelRun ?? (() => unstubbed("cancelRun")),
 		list: overrides.list ?? Effect.sync(() => unstubbed("list")),
@@ -77,6 +96,14 @@ const statusOf = (raw) => WorkflowRunStatus.make({
 	...raw.conclusion != null ? { conclusion: raw.conclusion } : {},
 	url: raw.html_url
 });
+/** GitHub's `workflow-dispatch-response`; the id is `number | bigint` in the generated types. */
+const DispatchResponse = Schema.Struct({
+	workflow_run_id: Schema.Union([Schema.Number, Schema.BigInt]),
+	run_url: Schema.String,
+	html_url: Schema.String
+});
+const decodeDispatchResponse = Schema.decodeUnknownEffect(DispatchResponse);
+const decodeDispatchedRun = Schema.decodeUnknownEffect(DispatchedRun);
 const make = (client) => {
 	const dispatch = Effect.fn("WorkflowDispatch.dispatch")(function* (workflow, ref, inputs) {
 		const { owner, repo } = yield* Repo;
@@ -94,6 +121,30 @@ const make = (client) => {
 			...inputs !== void 0 ? { inputs } : {}
 		});
 	});
+	const dispatchWithRun = Effect.fn("WorkflowDispatch.dispatchWithRun")(function* (workflow, ref, inputs) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			workflow,
+			ref
+		});
+		const data = yield* client.request("POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches", {
+			owner,
+			repo,
+			workflow_id: workflow,
+			ref,
+			...inputs !== void 0 ? { inputs } : {},
+			return_run_details: true
+		});
+		if (data === "" || data === null) return Option.none();
+		const run = yield* decodeDispatchResponse(data).pipe(Effect.flatMap((raw) => decodeDispatchedRun({
+			runId: numericId(raw.workflow_run_id),
+			runUrl: raw.run_url,
+			htmlUrl: raw.html_url
+		})), Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode("WorkflowDispatch.dispatchWithRun", "GitHub returned unexpected run details", error))));
+		return Option.some(run);
+	});
 	const runStatus = Effect.fn("WorkflowDispatch.runStatus")(function* (runId) {
 		const { owner, repo } = yield* Repo;
 		yield* Effect.annotateCurrentSpan({
@@ -126,6 +177,7 @@ const make = (client) => {
 	});
 	return {
 		dispatch,
+		dispatchWithRun,
 		runStatus,
 		cancelRun: Effect.fn("WorkflowDispatch.cancelRun")(function* (runId) {
 			const { owner, repo } = yield* Repo;
@@ -154,8 +206,8 @@ const make = (client) => {
 				attempts
 			});
 			const dispatchedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
-			yield* dispatch(workflow, ref, options?.inputs);
-			const findRun = Effect.gen(function* () {
+			const dispatched = yield* dispatchWithRun(workflow, ref, options?.inputs);
+			const findRun = Option.isSome(dispatched) ? Effect.map(runStatus(dispatched.value.runId), Option.some) : Effect.gen(function* () {
 				const match = (yield* client.paginate("GET /repos/{owner}/{repo}/actions/runs", {
 					owner,
 					repo,
@@ -179,4 +231,4 @@ const make = (client) => {
 };
 
 //#endregion
-export { WorkflowDispatch, WorkflowRunStatus };
+export { DispatchedRun, WorkflowDispatch, WorkflowRunStatus };

package/index.d.ts

@@ -4253,6 +4253,25 @@ export declare class WorkflowRunStatus extends WorkflowRunStatus_base {
   /** Has the run finished, whatever the outcome? */
   get isDone(): boolean;
 }
+declare const DispatchedRun_base: Schema.Class<DispatchedRun, Schema.Struct<{
+  /** The created run's numeric id. */
+  readonly runId: Schema.Int;
+  /** The run's API URL. */
+  readonly runUrl: Schema.String;
+  /** The run's web URL. */
+  readonly htmlUrl: Schema.String;
+}>, {}>;
+/**
+ * The run a `workflow_dispatch` created, as GitHub reports it when asked.
+ *
+ * @remarks
+ * Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+ * directly with {@link WorkflowDispatchShape.runStatus} and
+ * {@link WorkflowDispatchShape.cancelRun}.
+ *
+ * @public
+ */
+export declare class DispatchedRun extends DispatchedRun_base {}
 /**
  * One workflow defined in the repository.
  *
@@ -4293,8 +4312,34 @@ interface PollOptions {
  * @public
  */
 interface WorkflowDispatchShape {
-  /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
+  /**
+   * Fire a `workflow_dispatch` event and discard GitHub's answer; use
+   * {@link WorkflowDispatchShape.dispatchWithRun} when the run id is needed.
+   */
   readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Fire a `workflow_dispatch` event and report the run it created.
+   *
+   * @remarks
+   * Sends the same request as {@link WorkflowDispatchShape.dispatch} with
+   * `return_run_details: true`. GitHub then answers 200 with the run's id and
+   * URLs, which arrive as `Option.some` of a {@link DispatchedRun}; a 200 body
+   * that does not have that shape fails with a `decode` `GitHubError`.
+   *
+   * A 204 with no body is `Option.none()`. That is what a GitHub Enterprise
+   * Server predating the field answers — it ignores `return_run_details` and
+   * still dispatches — so it is **not a failure**: the workflow was dispatched,
+   * the server just did not say which run it created.
+   *
+   * Under `GitHubClient.layerFixture`, stub the 204 the way every other
+   * no-body route is stubbed: answer the dispatch route with `null`. `""`
+   * (what octokit itself hands back for an empty body) works too.
+   *
+   * Every failure of the request itself (a 404 for an unknown workflow, a 422
+   * for a workflow without a `workflow_dispatch` trigger, …) is the
+   * `GitHubError` the client classified, passed through unchanged.
+   */
+  readonly dispatchWithRun: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<Option.Option<DispatchedRun>, GitHubError, Repo>;
   /** Read one workflow run's status. */
   readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
   /**
@@ -4330,8 +4375,15 @@ interface WorkflowDispatchShape {
    * The wait is `Effect.repeat` with a predicate over the **success** value, so
    * "not finished yet" is never an error. If the run is not found finished
    * within `poll.timeout`, it fails with a `rejected` `GitHubError` (status
-   * 408). The run is matched by branch, creation time and workflow path, so
-   * concurrent dispatches of the same workflow on the same ref can be confused.
+   * 408).
+   *
+   * The run is identified by {@link WorkflowDispatchShape.dispatchWithRun}:
+   * when GitHub reports the run it created, exactly that run is polled, so
+   * concurrent dispatches cannot be confused. When it does not (a 204 from a
+   * GitHub Enterprise Server predating `return_run_details`), the run is found
+   * instead by branch, creation time and workflow path — and on that fallback
+   * alone, concurrent dispatches of the same workflow on the same ref can be
+   * confused.
    */
   readonly dispatchAndWait: (workflow: string, ref: string, options?: {
     readonly inputs?: Record<string, string> | undefined;

package/index.js

@@ -27,7 +27,7 @@ import { RepositorySecurity } from "./RepositorySecurity.js";
 import { RepositoryVariable } from "./RepositoryVariable.js";
 import { Ruleset } from "./Ruleset.js";
 import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, TokenPermissionError, TokenPermissions } from "./TokenPermissions.js";
-import { WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
+import { DispatchedRun, WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
 import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
 
-export { ActionsOidc, ActionsOidcClaims, Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeploymentEnvironment, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };
+export { ActionsOidc, ActionsOidcClaims, Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeploymentEnvironment, DispatchedRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [