@effected/github 0.11.0 → 0.13.0

package/GitHubError.js

@@ -25,6 +25,53 @@ const GitHubErrorKind = Schema.Literals([
 	"decode"
 ]);
 /**
+* The validation codes GitHub documents for a 422's `errors[].code`.
+*
+* @remarks
+* The complete documented set. Only `already_exists` earns its own
+* {@link GitHubErrorKind}; every other code classifies as `rejected`, and a
+* caller that needs to tell them apart reads {@link GitHubError}'s `validation`
+* or uses {@link GitHubError.hasValidationCode}.
+*
+* `missing` is the one that looks like `notFound` and is not: it names a
+* resource the request *referred to* — a commit sha, an assignee — not the one
+* it acted on. Routing it to `notFound` would let every
+* `catchIf(GitHubError.hasKind("notFound"), …)` recovery swallow a bad argument.
+*
+* @public
+*/
+const GitHubValidationCode = Schema.Literals([
+	"missing",
+	"missing_field",
+	"invalid",
+	"already_exists",
+	"unprocessable",
+	"custom"
+]);
+/**
+* One entry from a failed response's `data.errors` array, as GitHub sent it.
+*
+* @remarks
+* Every field is optional because GitHub's entries vary by endpoint: the
+* releases endpoint sends `resource`, `code` and `field` with no `message`,
+* while a `custom` entry may carry only a `message`. `code` is a plain string
+* rather than {@link GitHubValidationCode} so an unexpected code cannot make
+* the error itself fail to construct: a refused request must still surface as
+* a `GitHubError`, never as a defect.
+*
+* @public
+*/
+var GitHubValidationEntry = class extends Schema.Class("GitHubValidationEntry")({
+	/** The resource type GitHub validated, e.g. `"Release"`. */
+	resource: Schema.optionalKey(Schema.String),
+	/** The parameter at fault, e.g. `"tag_name"`. */
+	field: Schema.optionalKey(Schema.String),
+	/** GitHub's validation code — one of {@link GitHubValidationCode} when documented. */
+	code: Schema.optionalKey(Schema.String),
+	/** GitHub's prose, when it sent any. */
+	message: Schema.optionalKey(Schema.String)
+}) {};
+/**
 * Every REST failure this package produces, from every resource.
 *
 * @remarks
@@ -60,6 +107,15 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 	* `retryable` boolean it used to travel with is now a derived getter.
 	*/
 	retryAfterMillis: Schema.optionalKey(Schema.Int),
+	/**
+	* GitHub's validation entries, when the failed response carried any.
+	*
+	* @remarks
+	* The structured half of a 422: branch on an entry's `code` and `field`
+	* rather than on `reason`. Absent when GitHub sent no `errors` array — some
+	* 422s ("Update is not a fast forward") are prose only.
+	*/
+	validation: Schema.optionalKey(Schema.Array(GitHubValidationEntry)),
 	/** The underlying throwable, when one exists. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
@@ -138,6 +194,7 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 			reason: facts.reason,
 			...facts.status !== void 0 ? { status: facts.status } : {},
 			...retryAfterMillis !== void 0 ? { retryAfterMillis } : {},
+			...facts.validation.length > 0 ? { validation: facts.validation } : {},
 			cause: error
 		});
 	}
@@ -160,6 +217,30 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 		const set = new Set(kinds);
 		return (error) => set.has(error.kind);
 	}
+	/**
+	* A predicate over GitHub's validation codes, for `Effect.catchIf`.
+	*
+	* @remarks
+	* Matches when any entry in {@link GitHubError}'s `validation` carries one of
+	* the codes. Use it for the distinctions {@link GitHubErrorKind} deliberately
+	* does not draw, such as a `missing_field` against an `invalid`.
+	*
+	* @example
+	* ```ts
+	* import { GitHubError } from "@effected/github";
+	* import { Effect } from "effect";
+	*
+	* declare const create: Effect.Effect<void, GitHubError>;
+	*
+	* const tolerant = create.pipe(
+	*   Effect.catchIf(GitHubError.hasValidationCode("missing"), () => Effect.void),
+	* );
+	* ```
+	*/
+	static hasValidationCode(...codes) {
+		const set = new Set(codes);
+		return (error) => error.validation?.some((entry) => entry.code !== void 0 && set.has(entry.code)) ?? false;
+	}
 };
 /**
 * Read an unknown throwable structurally.
@@ -176,7 +257,7 @@ const readThrowable = (error) => {
 		status: void 0,
 		headers: void 0,
 		reason: String(error),
-		detailMessages: []
+		validation: []
 	};
 	const record = error;
 	const response = asRecord(record.response);
@@ -186,7 +267,7 @@ const readThrowable = (error) => {
 		status: typeof record.status === "number" ? record.status : void 0,
 		headers,
 		reason: sanitizeReason(typeof record.message === "string" ? record.message : String(error)),
-		detailMessages: readDetailMessages(data)
+		validation: readValidation(data)
 	};
 };
 const asRecord = (value) => typeof value === "object" && value !== null ? value : void 0;
@@ -205,18 +286,32 @@ const sanitizeReason = (message) => {
 	return trimmed;
 };
 const MAX_REASON_LENGTH = 500;
-/** GitHub's validation failures arrive as `data.errors[].message`. */
-const readDetailMessages = (data) => {
+/** GitHub's validation failures arrive as `data.errors[]` entries. */
+const readValidation = (data) => {
 	const errors = data?.errors;
 	if (!Array.isArray(errors)) return [];
-	const messages = [];
-	for (const entry of errors) {
-		const message = asRecord(entry)?.message;
-		if (typeof message === "string") messages.push(message);
+	const entries = [];
+	for (const raw of errors) {
+		const record = asRecord(raw);
+		if (record === void 0) continue;
+		const resource = stringField(record, "resource");
+		const field = stringField(record, "field");
+		const code = stringField(record, "code");
+		const message = stringField(record, "message");
+		if (resource === void 0 && field === void 0 && code === void 0 && message === void 0) continue;
+		entries.push(GitHubValidationEntry.make({
+			...resource !== void 0 ? { resource } : {},
+			...field !== void 0 ? { field } : {},
+			...code !== void 0 ? { code } : {},
+			...message !== void 0 ? { message } : {}
+		}));
 	}
-	return messages;
+	return entries;
 };
+const stringField = (record, key) => typeof record[key] === "string" ? record[key] : void 0;
 const ALREADY_EXISTS = "already exists";
+/** GitHub's documented validation-error code for a duplicate resource. */
+const ALREADY_EXISTS_CODE = "already_exists";
 const classify = (facts, retryAfterMillis) => {
 	const { status } = facts;
 	if (status === void 0) return "transport";
@@ -228,9 +323,16 @@ const classify = (facts, retryAfterMillis) => {
 	if (status === 422 || status === 409) return saysAlreadyExists(facts) ? "alreadyExists" : "rejected";
 	return "rejected";
 };
+/**
+* @remarks
+* The structured code is the authority — the releases endpoint sends it with
+* no message at all. The prose checks cover endpoints that say so only in
+* words, such as `/git/refs` answering "Reference already exists".
+*/
 const saysAlreadyExists = (facts) => {
+	if (facts.validation.some((entry) => entry.code === ALREADY_EXISTS_CODE)) return true;
 	if (facts.reason.toLowerCase().includes(ALREADY_EXISTS)) return true;
-	return facts.detailMessages.some((message) => message.toLowerCase().includes(ALREADY_EXISTS));
+	return facts.validation.some((entry) => entry.message?.toLowerCase().includes(ALREADY_EXISTS) ?? false);
 };
 /**
 * Re-exported for the client, which reads the same headers on the **success**
@@ -251,4 +353,4 @@ const readRateLimitHeaders = (headers) => {
 };
 
 //#endregion
-export { GitHubError, GitHubErrorKind, readRateLimitHeaders };
+export { GitHubError, GitHubErrorKind, GitHubValidationCode, GitHubValidationEntry, readRateLimitHeaders };

package/README.md

@@ -238,6 +238,21 @@ const program = upsertBranch.pipe(
 );
 ```
 
+A 422 also carries GitHub's validation entries as `validation`, each a `GitHubValidationEntry` with the `resource`, `field`, `code` and `message` GitHub sent. Only `already_exists` gets a `kind` of its own; for the other documented codes (`GitHubValidationCode`), branch with `hasValidationCode` rather than reading `reason`:
+
+```ts
+import { GitHubError } from "@effected/github";
+import { Effect } from "effect";
+
+declare const createRelease: Effect.Effect<void, GitHubError>;
+
+const program = createRelease.pipe(
+  Effect.catchIf(GitHubError.hasValidationCode("missing_field", "invalid"), (error) =>
+    Effect.logError(`bad release parameters: ${error.validation?.map((entry) => entry.field).join(", ")}`),
+  ),
+);
+```
+
 Retrying is handled once, in the client: `RetryPolicy.default` retries a `transport` or `rateLimited` failure with full-jitter backoff, honoring GitHub's `retry-after` header up to a configurable ceiling. `RetryPolicy.none` disables it. A `notFound`, `rejected` or `unauthorized` failure never retries — it cannot change its mind between attempts.
 
 ## Testing
@@ -282,7 +297,7 @@ const TestClient = GitHubClient.layerFixture(fixtures);
 - `Repo` / `RepoRef` — the `{ owner, repo }` coordinate, resolved per call through `R`, with `Repo.provide` for multi-repository programs.
 - `GitHubRepository` — the repository's settings as GitHub's own generated type, plus `defaultBranch`, `nodeId`, `ownerType` for gating organization-only fields, and `applySettings` reporting the keys it actually sent.
 - `repositoryPatch` / `RepositoryPatchDraft` — build an `updateSettings` patch from fields that may be `undefined`, under `exactOptionalPropertyTypes`, without a cast.
-- `GitHubError` / `GitHubGraphQLError` — one error per transport, `kind`-routed with `hasKind` for `Effect.catchIf`.
+- `GitHubError` / `GitHubGraphQLError` — one error per transport, `kind`-routed with `hasKind` for `Effect.catchIf`; a REST 422's validation entries ride on `validation`, matched with `hasValidationCode`.
 - `RetryPolicy` — the client's one retry policy: full-jitter backoff, server-advised delays honored up to a ceiling.
 - `GitHubApp` — App JWT signing, installation token minting/revocation, app and installation identity, and `clientLayer` for an App-authenticated `GitHubClient`.
 - `GitBranch` / `GitTag` — Git Database API refs, with `upsert` collapsing the create-or-reset dance to one call and `GitTag.latestSemver` picking the newest version-shaped tag in one pass.

package/index.d.ts

@@ -19,6 +19,47 @@ import { SemVer } from "@effected/semver";
  * @public
  */
 export declare const GitHubErrorKind: Schema.Literals<readonly ["notFound", "alreadyExists", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
+/**
+ * The validation codes GitHub documents for a 422's `errors[].code`.
+ *
+ * @remarks
+ * The complete documented set. Only `already_exists` earns its own
+ * {@link GitHubErrorKind}; every other code classifies as `rejected`, and a
+ * caller that needs to tell them apart reads {@link GitHubError}'s `validation`
+ * or uses {@link GitHubError.hasValidationCode}.
+ *
+ * `missing` is the one that looks like `notFound` and is not: it names a
+ * resource the request *referred to* — a commit sha, an assignee — not the one
+ * it acted on. Routing it to `notFound` would let every
+ * `catchIf(GitHubError.hasKind("notFound"), …)` recovery swallow a bad argument.
+ *
+ * @public
+ */
+export declare const GitHubValidationCode: Schema.Literals<readonly ["missing", "missing_field", "invalid", "already_exists", "unprocessable", "custom"]>;
+declare const GitHubValidationEntry_base: Schema.Class<GitHubValidationEntry, Schema.Struct<{
+  /** The resource type GitHub validated, e.g. `"Release"`. */
+  readonly resource: Schema.optionalKey<Schema.String>;
+  /** The parameter at fault, e.g. `"tag_name"`. */
+  readonly field: Schema.optionalKey<Schema.String>;
+  /** GitHub's validation code — one of {@link GitHubValidationCode} when documented. */
+  readonly code: Schema.optionalKey<Schema.String>;
+  /** GitHub's prose, when it sent any. */
+  readonly message: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One entry from a failed response's `data.errors` array, as GitHub sent it.
+ *
+ * @remarks
+ * Every field is optional because GitHub's entries vary by endpoint: the
+ * releases endpoint sends `resource`, `code` and `field` with no `message`,
+ * while a `custom` entry may carry only a `message`. `code` is a plain string
+ * rather than {@link GitHubValidationCode} so an unexpected code cannot make
+ * the error itself fail to construct: a refused request must still surface as
+ * a `GitHubError`, never as a defect.
+ *
+ * @public
+ */
+export declare class GitHubValidationEntry extends GitHubValidationEntry_base {}
 declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"GitHubError", {
   /** Structural routing. Branch on this, never on the rendered message. */
   readonly kind: Schema.Literals<readonly ["notFound", "alreadyExists", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
@@ -38,6 +79,15 @@ declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"G
    * `retryable` boolean it used to travel with is now a derived getter.
    */
   readonly retryAfterMillis: Schema.optionalKey<Schema.Int>;
+  /**
+   * GitHub's validation entries, when the failed response carried any.
+   *
+   * @remarks
+   * The structured half of a 422: branch on an entry's `code` and `field`
+   * rather than on `reason`. Absent when GitHub sent no `errors` array — some
+   * 422s ("Update is not a fast forward") are prose only.
+   */
+  readonly validation: Schema.optionalKey<Schema.$Array<typeof GitHubValidationEntry>>;
   /** The underlying throwable, when one exists. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
@@ -109,6 +159,27 @@ export declare class GitHubError extends GitHubError_base {
    * ```
    */
   static hasKind(...kinds: ReadonlyArray<(typeof GitHubErrorKind.literals)[number]>): (error: GitHubError) => boolean;
+  /**
+   * A predicate over GitHub's validation codes, for `Effect.catchIf`.
+   *
+   * @remarks
+   * Matches when any entry in {@link GitHubError}'s `validation` carries one of
+   * the codes. Use it for the distinctions {@link GitHubErrorKind} deliberately
+   * does not draw, such as a `missing_field` against an `invalid`.
+   *
+   * @example
+   * ```ts
+   * import { GitHubError } from "@effected/github";
+   * import { Effect } from "effect";
+   *
+   * declare const create: Effect.Effect<void, GitHubError>;
+   *
+   * const tolerant = create.pipe(
+   *   Effect.catchIf(GitHubError.hasValidationCode("missing"), () => Effect.void),
+   * );
+   * ```
+   */
+  static hasValidationCode(...codes: ReadonlyArray<(typeof GitHubValidationCode.literals)[number]>): (error: GitHubError) => boolean;
 }
 //#endregion
 //#region src/GraphQL.d.ts

package/index.js

@@ -1,4 +1,4 @@
-import { GitHubError, GitHubErrorKind } from "./GitHubError.js";
+import { GitHubError, GitHubErrorKind, GitHubValidationCode, GitHubValidationEntry } from "./GitHubError.js";
 import { GitHubGraphQLError, GraphQLDocument, GraphQLErrorEntry } from "./GraphQL.js";
 import { RateLimitSnapshot, RetryPolicy } from "./Resilience.js";
 import { GitHubClient } from "./GitHubClient.js";
@@ -28,4 +28,4 @@ import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, Toke
 import { WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
 import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
 
-export { 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, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, 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 { 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, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, 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.11.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -38,8 +38,8 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/github-references": "^0.4.0",
-		"@effected/semver": "^0.8.0",
+		"@effected/github-references": "^0.5.0",
+		"@effected/semver": "^0.9.0",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^15.0.0",
 		"@octokit/types": "^18.0.0",
@@ -48,7 +48,7 @@
 		"universal-github-app-jwt": "^2.2.2"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.116"
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"