@effected/github 0.25.1 → 0.27.0

package/GitHubRepository.js

@@ -1,4 +1,5 @@
 import { GraphQLDocument } from "./GraphQL.js";
+import { reservedSettingKey } from "./internal/requestOptions.js";
 import { unstubbed, unstubbedRead } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
@@ -8,7 +9,7 @@ import { Context, Effect, Layer, Schema } from "effect";
 // src/GitHubRepository.ts
 /**
 * A {@link RepositoryPatch} from a draft, dropping every explicitly-`undefined`
-* field.
+* field, plus any settings octokit's types do not know yet.
 *
 * @remarks
 * The supported spelling for "apply only what was configured" — the natural
@@ -18,6 +19,13 @@ import { Context, Effect, Layer, Schema } from "effect";
 * `PATCH` treats an absent field as "leave it alone", while an explicit `null`
 * or `undefined` is a value.
 *
+* `options.extra` is the typed escape hatch for a setting GitHub accepts
+* before octokit's generated types declare it: the draft stays checked, and
+* only the extras ride unchecked. The result is still typed `RepositoryPatch`,
+* and `GitHubRepository.updateSettings` sends every key it carries. A known key
+* passed through `extra` throws a `RangeError` rather than skipping the draft's
+* type check (see {@link RepositoryPatchOptions.extra}).
+*
 * A key-by-key loop still defeats TypeScript's correlation between two indexed
 * accesses (`draft[key] = source[key]` over a union `key`), which no helper can
 * fix — build the draft as a literal where you can.
@@ -27,23 +35,60 @@ import { Context, Effect, Layer, Schema } from "effect";
 * import { repositoryPatch } from "@effected/github";
 *
 * // `config.has_issues` is `boolean | undefined`; absent fields drop out.
-* const patch = repositoryPatch({
-*   has_issues: config.has_issues,
-*   has_wiki: config.has_wiki,
-*   description: config.description,
-* });
+* const patch = repositoryPatch(
+*   {
+*     has_issues: config.has_issues,
+*     has_wiki: config.has_wiki,
+*     description: config.description,
+*   },
+*   // A setting GitHub accepts before octokit's types declare it.
+*   { extra: { has_new_feature: true } },
+* );
 * ```
 *
 * @param draft - The fields to apply, any of which may be `undefined`.
+* @param options - `extra`: settings the generated type does not declare.
 * @returns A patch carrying only the fields that were actually set.
 *
 * @public
 */
-const repositoryPatch = (draft) => {
+const repositoryPatch = (draft, options) => {
 	const out = {};
-	for (const [key, value] of Object.entries(draft)) if (value !== void 0) out[key] = value;
+	for (const [key, value] of Object.entries(draft)) {
+		refuseReserved(key);
+		if (value !== void 0) out[key] = value;
+	}
+	for (const [key, value] of Object.entries(options?.extra ?? {})) {
+		refuseReserved(key);
+		if (Object.hasOwn(GRAPHQL_ONLY_SETTINGS, key)) throw new RangeError(`repositoryPatch: "${key}" can only be set through GraphQL; use GitHubRepository.applySettings, not a REST patch`);
+		if (REPOSITORY_REST_SETTING_KEYS.has(key)) throw new RangeError(`repositoryPatch: "${key}" is a declared repository setting; pass it in the draft, where its type is checked, not in extra`);
+		if (value !== void 0) out[key] = value;
+	}
 	return out;
 };
+/** A `RangeError` for a key octokit would read as something other than a setting. */
+const refuseReserved = (key) => {
+	const reason = reservedSettingKey(key);
+	if (reason !== void 0) throw new RangeError(`repositoryPatch: "${key}" ${reason}; it is never sent`);
+};
+/**
+* The parameters of a repository PATCH, with the settings as octokit's `data`.
+*
+* @remarks
+* `data` is octokit's explicit body: `@octokit/endpoint` sends it verbatim and
+* reads no key inside it as a request option or a path parameter. Spreading
+* the settings beside `owner` and `repo` instead lets an open map choose the
+* request's host, headers, fetch implementation or path, which is how an
+* authenticated PATCH reaches another host with the token attached. So the
+* confinement holds by construction; the reserved-name refusals are defence in
+* depth. The generated parameter type has no `data`, so the cast is here, on
+* the one shape both write paths send.
+*/
+const patchParams = (owner, repo, body) => ({
+	owner,
+	repo,
+	data: body
+});
 /**
 * Fields in the user-facing `security_and_analysis` block that GitHub accepts
 * as `{ status: "enabled" | "disabled" }`.
@@ -268,26 +313,29 @@ const make = (client) => {
 				repo,
 				fields: Object.keys(patch).length
 			});
-			return yield* client.request("PATCH /repos/{owner}/{repo}", {
-				...preparePatch(patch),
-				owner,
-				repo
-			});
+			return yield* client.request("PATCH /repos/{owner}/{repo}", patchParams(owner, repo, preparePatch(patch)));
 		}),
 		defaultBranch: Effect.map(settings, (repository) => repository.default_branch),
 		nodeId: Effect.map(settings, (repository) => repository.node_id),
 		ownerType,
-		applySettings: Effect.fn("GitHubRepository.applySettings")(function* (input) {
+		applySettings: Effect.fn("GitHubRepository.applySettings")(function* (input, options) {
 			const { owner, repo } = yield* Repo;
+			const sendUnknown = options?.unknownKeys === "send";
 			yield* Effect.annotateCurrentSpan({
 				owner,
-				repo
+				repo,
+				unknownKeys: sendUnknown ? "send" : "ignore"
 			});
 			const rest = {};
 			const graphql = {};
 			const graphqlKeys = [];
 			const ignored = [];
+			const unverified = [];
 			for (const [key, value] of Object.entries(input)) {
+				if (reservedSettingKey(key) !== void 0) {
+					ignored.push(key);
+					continue;
+				}
 				const graphqlField = Object.hasOwn(GRAPHQL_ONLY_SETTINGS, key) ? GRAPHQL_ONLY_SETTINGS[key] : void 0;
 				if (graphqlField !== void 0) {
 					graphql[graphqlField] = value;
@@ -295,19 +343,22 @@ const make = (client) => {
 					continue;
 				}
 				const removedIn = Object.hasOwn(REMOVED_BY_PINNED_VERSION, key) ? REMOVED_BY_PINNED_VERSION[key] : void 0;
-				if (!REPOSITORY_REST_SETTING_KEYS.has(key) || removedIn !== void 0 && client.apiVersion >= removedIn) {
+				if (removedIn !== void 0 && client.apiVersion >= removedIn) {
 					ignored.push(key);
 					continue;
 				}
+				if (!REPOSITORY_REST_SETTING_KEYS.has(key)) {
+					if (!sendUnknown) {
+						ignored.push(key);
+						continue;
+					}
+					unverified.push(key);
+				}
 				rest[key] = value;
 			}
 			const prepared = preparePatch(rest);
 			const restKeys = Object.keys(prepared);
-			if (restKeys.length > 0) yield* client.request("PATCH /repos/{owner}/{repo}", {
-				...prepared,
-				owner,
-				repo
-			});
+			if (restKeys.length > 0) yield* client.request("PATCH /repos/{owner}/{repo}", patchParams(owner, repo, prepared));
 			if (Object.keys(graphql).length > 0) {
 				const repository = yield* client.request("GET /repos/{owner}/{repo}", {
 					owner,
@@ -321,7 +372,8 @@ const make = (client) => {
 			return {
 				rest: restKeys,
 				graphql: graphqlKeys,
-				ignored
+				ignored,
+				unverified: unverified.filter((key) => Object.hasOwn(prepared, key))
 			};
 		})
 	};

package/GraphQL.js

@@ -1,4 +1,5 @@
 import { retryAfterMillisFrom } from "./internal/headers.js";
+import { scrubThrowable } from "./internal/scrub.js";
 import { Schema } from "effect";
 
 // src/GraphQL.ts
@@ -78,6 +79,11 @@ var GitHubGraphQLError = class GitHubGraphQLError extends Schema.TaggedError()("
 	* failure with a `status`. Both arrive as throwables and both are read
 	* structurally, for the same reason the REST classifier does it — the error
 	* classes live in packages this one does not declare.
+	*
+	* The kept `cause` is the same credential-free copy
+	* {@link GitHubError.fromOctokit} keeps: the GraphQL document, its variables
+	* and any partial `data` are dropped with the rest of the request and response
+	* bodies.
 	*/
 	static fromThrowable(operation, error, nowMillis) {
 		const record = typeof error === "object" && error !== null ? error : void 0;
@@ -92,7 +98,7 @@ var GitHubGraphQLError = class GitHubGraphQLError extends Schema.TaggedError()("
 			reason,
 			errors: entries,
 			...retryAfterMillis !== void 0 ? { retryAfterMillis } : {},
-			cause: error
+			cause: scrubThrowable(error)
 		});
 	}
 };

package/README.md

@@ -8,10 +8,10 @@
 Typed GitHub REST and GraphQL for [Effect](https://effect.website) v4. `client.request("GET /repos/{owner}/{repo}", { owner, repo })` types both the parameters and the returned `data` from the route literal alone — no `operation: string`, no callback, no cast. One `GitHubError` covers every REST failure with a `kind` you branch on instead of grepping a message, one pagination engine backs every paginating route and `client.request`'s `Stream` form, and a set of resource services (`GitBranch`, `GitTag`, `CheckRun`, `PullRequest`, `PullRequestComment`, `GitHubRelease`, `Attestation`) turn multi-call dances — "does this branch already exist?", "conclude this check run no matter how the program exits" — into one call. A second tier writes the configuration half: secrets, variables, rulesets, deployment environments, the security toggles and CodeQL default setup. `GitHubApp` mints and revokes installation tokens for App auth.
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
-> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
 > makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
 > `@effect/*` versions on the line the kit is built and tested against, install
-> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
 > complete and may change across `0.x` releases. Pin an exact version — even a
@@ -25,7 +25,7 @@ Hand-rolled octokit wrappers tend to converge on the same shape: a `rest<T>(oper
 
 The error model gets the same treatment. `GitHubError.kind` is a literal union (`notFound`, `alreadyExists`, `rejected`, `unauthorized`, `rateLimited`, `transport`, `decode`) produced by one classification step, `GitHubError.fromOctokit`, instead of one hand-written mapper per resource. `kind: "alreadyExists"` is what makes `GitBranch.upsert` and `GitTag.upsert` a single round trip in the common case, rather than a create-then-catch-then-check-then-reset dance repeated at every call site that needs it.
 
-This package also owns the octokit runtime so nothing downstream has to. `@octokit/rest` and `@octokit/auth-app` are deliberately absent — the rest wrapper is a request-logging plugin plus 1.4 MB of duplicate endpoint types, and `auth-app` drags in `createOAuthUserAuth`, roughly 492 KB of OAuth machinery this package never calls. GitHub App JWTs are signed by the kit's own `@effected/jwt` instead: WebCrypto RS256 with no runtime dependencies, so App auth runs on Cloudflare Workers as well as Node. A consumer that only authenticates with a token it already holds never links the JWT signer at all: the App-authenticated layer lives in its own module (`GitHubApp`), and nothing here is gathered into a namespace object that would defeat that split.
+This package also owns the octokit runtime so nothing downstream has to. `@octokit/rest` and `@octokit/auth-app` are deliberately absent — the rest wrapper is a request-logging plugin plus 1.4 MB of duplicate endpoint types, and `auth-app` drags in `createOAuthUserAuth`, roughly 492 KB of OAuth machinery this package never calls. GitHub App JWTs are signed by the kit's own `@effected/jwt` instead, over core `effect/jose`: RS256 with no extra runtime dependencies, so App auth runs on Cloudflare Workers as well as Node. The App layers (`GitHubApp.layer`, `layerWith`, `clientLayer`, `appClientLayer`) require core's `Signature` service; provide `Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))` from `effect/crypto` once at the edge. A consumer that only authenticates with a token it already holds never links the JWT signer at all: the App-authenticated layer lives in its own module (`GitHubApp`), and nothing here is gathered into a namespace object that would defeat that split.
 
 ## Install