@automate.ax/integration-contracts 0.88.2 → 0.88.3

package/src/github/openapi-types.ts

@@ -0,0 +1,59 @@
+import type { Encodable } from "@automate.ax/codec"
+import type { components } from "./openapi-types.generated"
+import type { GitHubRestResourceName } from "./rest-schemas"
+import type { GitHubWebhookAction } from "./webhook-operations"
+
+type GitHubOpenApiSchemas = components["schemas"]
+
+/** Generated component names that represent webhook operation roots. */
+type GitHubWebhookSchemaName = Extract<
+  keyof GitHubOpenApiSchemas,
+  `webhook-event-${string}`
+>
+
+/** Frozen GitHub OpenAPI webhook operation identifier. */
+export type GitHubWebhookOperation =
+  GitHubWebhookSchemaName extends `webhook-event-${infer TOperation}`
+    ? TOperation
+    : never
+
+type GitHubEncodable<TValue> = 0 extends 1 & TValue
+  ? Encodable
+  : unknown extends TValue
+    ? Encodable
+    : TValue extends null | undefined | boolean | number | string
+      ? TValue
+      : TValue extends Record<string, never>
+        ? Record<string, Encodable>
+        : TValue extends readonly (infer TItem)[]
+          ? GitHubEncodable<TItem>[]
+          : TValue extends object
+            ? keyof TValue extends never
+              ? Record<string, Encodable>
+              : { [TKey in keyof TValue]: GitHubEncodable<TValue[TKey]> }
+            : never
+
+/** Public response type generated from the frozen GitHub REST contract. */
+export type GitHubRestResource<TResource extends GitHubRestResourceName> =
+  GitHubEncodable<GitHubOpenApiSchemas[`rest-response-${TResource}`]>
+
+/** Public event type generated from the frozen GitHub webhook contract. */
+export type GitHubWebhookPayload<TOperation extends GitHubWebhookOperation> =
+  TOperation extends GitHubWebhookOperation
+    ? GitHubWebhookPayloadForOperation<TOperation>
+    : never
+
+/** Exact generated payload for one classified webhook operation. */
+type GitHubWebhookPayloadForOperation<
+  TOperation extends GitHubWebhookOperation,
+> =
+  GitHubEncodable<
+    GitHubOpenApiSchemas[Extract<
+      `webhook-event-${TOperation}`,
+      keyof GitHubOpenApiSchemas
+    >]
+  > extends infer TPayload
+    ? GitHubWebhookAction<TOperation> extends never
+      ? TPayload
+      : Omit<TPayload, "action"> & { action: GitHubWebhookAction<TOperation> }
+    : never

package/src/github/resources.ts

@@ -1,357 +1,160 @@
-import type { Encodable } from "@automate.ax/codec"
-import type { Octokit } from "@octokit/rest"
 import * as z from "zod"
+import type { GitHubRestResource } from "./openapi-types"
+import { githubRestResourceSchema } from "./rest-schemas"
 
-/** Official repository response used by the exported runtime schema. */
-type GitHubRepository = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["get"]>
->["data"] &
-  Encodable
+/** Complete repository response exposed by repository actions. */
+export type GitHubRepository = GitHubRestResource<"repository">
 
-/** Official installation repository summary used by the list schema. */
-type GitHubRepositorySummary = Awaited<
-  ReturnType<Octokit["rest"]["apps"]["listReposAccessibleToInstallation"]>
->["data"]["repositories"][number] &
-  Encodable
+/** Installation repository summary exposed by repository listing. */
+export type GitHubRepositorySummary = GitHubRestResource<"repository-summary">
 
-/** Official repository content response used by the content schema. */
-type GitHubRepositoryContent = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getContent"]>
->["data"] &
-  Encodable
+/** File, directory, symlink, or submodule repository content response. */
+export type GitHubRepositoryContent = GitHubRestResource<"repository-content">
 
-/** Official file-write response used by the file commit schema. */
-type GitHubRepositoryFileCommit = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["createOrUpdateFileContents"]>
->["data"] &
-  Encodable
+/** Repository file write response. */
+export type GitHubRepositoryFileCommit = GitHubRestResource<"file-commit">
 
-/** Official file-deletion response used by the deletion schema. */
-type GitHubRepositoryFileDeletion = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["deleteFile"]>
->["data"] &
-  Encodable
+/** Repository file deletion response. */
+export type GitHubRepositoryFileDeletion = GitHubRestResource<"file-deletion">
 
-/** Official branch response used by the branch schema. */
-type GitHubBranch = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getBranch"]>
->["data"] &
-  Encodable
+/** Complete repository branch response. */
+export type GitHubBranch = GitHubRestResource<"branch">
 
-/** Official branch summary used by the branch list schema. */
-type GitHubBranchSummary = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["listBranches"]>
->["data"][number] &
-  Encodable
+/** Repository branch-list item. */
+export type GitHubBranchSummary = GitHubRestResource<"branch-summary">
 
-/** Official Git reference response used by the reference schema. */
-type GitHubReference = Awaited<
-  ReturnType<Octokit["rest"]["git"]["createRef"]>
->["data"] &
-  Encodable
+/** Git reference response. */
+export type GitHubReference = GitHubRestResource<"reference">
 
-/** Official Actions workflow response used by the workflow schema. */
-type GitHubWorkflow = Awaited<
-  ReturnType<Octokit["rest"]["actions"]["getWorkflow"]>
->["data"] &
-  Encodable
+/** GitHub Actions workflow response. */
+export type GitHubWorkflow = GitHubRestResource<"workflow">
 
-/** Official Actions workflow-run response used by the run schema. */
-type GitHubWorkflowRun = Awaited<
-  ReturnType<Octokit["rest"]["actions"]["getWorkflowRun"]>
->["data"] &
-  Encodable
+/** GitHub Actions workflow-run response. */
+export type GitHubWorkflowRun = GitHubRestResource<"workflow-run">
 
-/** Official Actions job response used by the job schema. */
-type GitHubWorkflowJob = Awaited<
-  ReturnType<Octokit["rest"]["actions"]["listJobsForWorkflowRun"]>
->["data"]["jobs"][number] &
-  Encodable
+/** GitHub Actions workflow-job response. */
+export type GitHubWorkflowJob = GitHubRestResource<"workflow-job">
 
-/** Official pull request file response used by the file schema. */
-type GitHubPullRequestFile = Awaited<
-  ReturnType<Octokit["rest"]["pulls"]["listFiles"]>
->["data"][number] &
-  Encodable
+/** Pull-request file response. */
+export type GitHubPullRequestFile = GitHubRestResource<"pull-request-file">
 
-/** Official pull request review response used by the review schema. */
-type GitHubPullRequestReview = Awaited<
-  ReturnType<Octokit["rest"]["pulls"]["createReview"]>
->["data"] &
-  Encodable
+/** Pull-request review response. */
+export type GitHubPullRequestReview = GitHubRestResource<"pull-request-review">
 
-/** Official review-comment response used by the comment schema. */
-type GitHubPullRequestReviewComment = Awaited<
-  ReturnType<Octokit["rest"]["pulls"]["getReviewComment"]>
->["data"] &
-  Encodable
+/** Pull-request review-comment response. */
+export type GitHubPullRequestReviewComment =
+  GitHubRestResource<"pull-request-review-comment">
 
-/** Official reviewer-request response used by the reviewer schema. */
-type GitHubPullRequestReviewRequest = Awaited<
-  ReturnType<Octokit["rest"]["pulls"]["requestReviewers"]>
->["data"] &
-  Encodable
+/** Pull-request reviewer-request response. */
+export type GitHubPullRequestReviewRequest =
+  GitHubRestResource<"pull-request-review-request">
 
-/** Official pull request branch-update response used by its schema. */
-type GitHubPullRequestBranchUpdate = Awaited<
-  ReturnType<Octokit["rest"]["pulls"]["updateBranch"]>
->["data"] &
-  Encodable
+/** Pull-request branch-update response. */
+export type GitHubPullRequestBranchUpdate =
+  GitHubRestResource<"pull-request-branch-update">
 
-/** Official release response used by the release schema. */
-type GitHubRelease = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getRelease"]>
->["data"] &
-  Encodable
+/** GitHub release response. */
+export type GitHubRelease = GitHubRestResource<"release">
 
-/** Official release-asset response used by the asset schema. */
-type GitHubReleaseAsset = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getReleaseAsset"]>
->["data"] &
-  Encodable
+/** GitHub release-asset response. */
+export type GitHubReleaseAsset = GitHubRestResource<"release-asset">
 
-/** Official deployment response used by the deployment schema. */
-type GitHubDeployment = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getDeployment"]>
->["data"] &
-  Encodable
+/** GitHub deployment response. */
+export type GitHubDeployment = GitHubRestResource<"deployment">
 
-/** Official deployment-creation response used by its result schema. */
-type GitHubDeploymentCreation = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["createDeployment"]>
->["data"] &
-  Encodable
+/** GitHub deployment-creation response or provider message. */
+export type GitHubDeploymentCreation = GitHubRestResource<"deployment-creation">
 
-/** Official deployment-status response used by the status schema. */
-type GitHubDeploymentStatus = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["createDeploymentStatus"]>
->["data"] &
-  Encodable
+/** GitHub deployment-status response. */
+export type GitHubDeploymentStatus = GitHubRestResource<"deployment-status">
 
-/** Official commit-status response used by the status schema. */
-type GitHubCommitStatus = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["createCommitStatus"]>
->["data"] &
-  Encodable
+/** GitHub commit-status response. */
+export type GitHubCommitStatus = GitHubRestResource<"commit-status">
 
-/** Official check-run response used by the check-run schema. */
-type GitHubCheckRun = Awaited<
-  ReturnType<Octokit["rest"]["checks"]["get"]>
->["data"] &
-  Encodable
+/** GitHub check-run response. */
+export type GitHubCheckRun = GitHubRestResource<"check-run">
 
-/** Official combined-status response used by the combined status schema. */
-type GitHubCombinedCommitStatus = Awaited<
-  ReturnType<Octokit["rest"]["repos"]["getCombinedStatusForRef"]>
->["data"] &
-  Encodable
+/** Combined commit-status response. */
+export type GitHubCombinedCommitStatus =
+  GitHubRestResource<"combined-commit-status">
 
 /** Current GitHub REST response for a successful workflow dispatch. */
-export interface GitHubWorkflowDispatchResult
-  extends Record<string, Encodable> {
-  /** Web URL for the created workflow run. */
-  html_url: string
+export type GitHubWorkflowDispatchResult =
+  GitHubRestResource<"workflow-dispatch">
 
-  /** API URL for the created workflow run. */
-  run_url: string
-
-  /** Stable ID of the created workflow run. */
-  workflow_run_id: number
-}
-
-const GITHUB_REPOSITORY_BASE_SCHEMA = z.looseObject({
-  full_name: z.string(),
-  id: z.number().int().positive(),
-  name: z.string(),
-})
-const GITHUB_REPOSITORY_CONTENT_BASE_SCHEMA = z.union([
-  z.looseObject({ path: z.string(), sha: z.string(), type: z.string() }),
-  z
-    .looseObject({ path: z.string(), sha: z.string(), type: z.string() })
-    .array(),
-])
-const GITHUB_FILE_COMMIT_BASE_SCHEMA = z.looseObject({
-  commit: z.looseObject({ sha: z.string() }),
-  content: z.looseObject({ path: z.string(), sha: z.string() }).nullable(),
-})
-const GITHUB_BRANCH_BASE_SCHEMA = z.looseObject({
-  commit: z.looseObject({ sha: z.string() }),
-  name: z.string(),
-})
-const GITHUB_REFERENCE_BASE_SCHEMA = z.looseObject({
-  object: z.looseObject({ sha: z.string(), type: z.string() }),
-  ref: z.string(),
-})
-const GITHUB_WORKFLOW_BASE_SCHEMA = z.looseObject({
-  id: z.number().int().positive(),
-  name: z.string(),
-  path: z.string(),
-  state: z.string(),
-})
-const GITHUB_WORKFLOW_RUN_BASE_SCHEMA = z.looseObject({
-  conclusion: z.string().nullable(),
-  html_url: z.string(),
-  id: z.number().int().positive(),
-  status: z.string().nullable(),
-})
-const GITHUB_WORKFLOW_JOB_BASE_SCHEMA = z.looseObject({
-  conclusion: z.string().nullable(),
-  id: z.number().int().positive(),
-  name: z.string(),
-  status: z.string(),
-})
-const GITHUB_PULL_REQUEST_FILE_BASE_SCHEMA = z.looseObject({
-  filename: z.string(),
-  sha: z.string(),
-  status: z.string(),
-})
-const GITHUB_PULL_REQUEST_REVIEW_BASE_SCHEMA = z.looseObject({
-  id: z.number().int().positive(),
-  state: z.string(),
-})
-const GITHUB_PULL_REQUEST_REVIEW_COMMENT_BASE_SCHEMA = z.looseObject({
-  body: z.string(),
-  id: z.number().int().positive(),
-  path: z.string(),
-})
-const GITHUB_PULL_REQUEST_BRANCH_UPDATE_BASE_SCHEMA = z.looseObject({
-  message: z.string(),
-  url: z.string(),
-})
-const GITHUB_RELEASE_BASE_SCHEMA = z.looseObject({
-  draft: z.boolean(),
-  id: z.number().int().positive(),
-  prerelease: z.boolean(),
-  tag_name: z.string(),
-})
-const GITHUB_RELEASE_ASSET_BASE_SCHEMA = z.looseObject({
-  browser_download_url: z.string(),
-  id: z.number().int().positive(),
-  name: z.string(),
-  size: z.number().int().nonnegative(),
-  state: z.string(),
-})
-const GITHUB_DEPLOYMENT_BASE_SCHEMA = z.looseObject({
-  environment: z.string(),
-  id: z.number().int().positive(),
-  ref: z.string(),
-})
-const GITHUB_DEPLOYMENT_CREATION_BASE_SCHEMA = z.union([
-  GITHUB_DEPLOYMENT_BASE_SCHEMA,
-  z.looseObject({ message: z.string() }),
-])
-const GITHUB_DEPLOYMENT_STATUS_BASE_SCHEMA = z.looseObject({
-  id: z.number().int().positive(),
-  state: z.string(),
-})
-const GITHUB_COMMIT_STATUS_BASE_SCHEMA = z.looseObject({
-  context: z.string(),
-  id: z.number().int().positive(),
-  state: z.string(),
-})
-const GITHUB_CHECK_RUN_BASE_SCHEMA = z.looseObject({
-  conclusion: z.string().nullable(),
-  head_sha: z.string(),
-  id: z.number().int().positive(),
-  name: z.string(),
-  status: z.string(),
-})
-
-export const GITHUB_REPOSITORY_SCHEMA = githubResourceSchema<GitHubRepository>(
-  GITHUB_REPOSITORY_BASE_SCHEMA,
-)
+export const GITHUB_REPOSITORY_SCHEMA =
+  githubRestResourceSchema<GitHubRepository>("repository")
 export const GITHUB_REPOSITORY_SUMMARY_SCHEMA =
-  githubResourceSchema<GitHubRepositorySummary>(GITHUB_REPOSITORY_BASE_SCHEMA)
+  githubRestResourceSchema<GitHubRepositorySummary>("repository-summary")
 export const GITHUB_REPOSITORY_CONTENT_SCHEMA =
-  githubResourceSchema<GitHubRepositoryContent>(
-    GITHUB_REPOSITORY_CONTENT_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubRepositoryContent>("repository-content")
 export const GITHUB_REPOSITORY_FILE_COMMIT_SCHEMA =
-  githubResourceSchema<GitHubRepositoryFileCommit>(
-    GITHUB_FILE_COMMIT_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubRepositoryFileCommit>("file-commit")
 export const GITHUB_REPOSITORY_FILE_DELETION_SCHEMA =
-  githubResourceSchema<GitHubRepositoryFileDeletion>(
-    GITHUB_FILE_COMMIT_BASE_SCHEMA,
-  )
-export const GITHUB_BRANCH_SCHEMA = githubResourceSchema<GitHubBranch>(
-  GITHUB_BRANCH_BASE_SCHEMA,
-)
+  githubRestResourceSchema<GitHubRepositoryFileDeletion>("file-deletion")
+export const GITHUB_BRANCH_SCHEMA =
+  githubRestResourceSchema<GitHubBranch>("branch")
 export const GITHUB_BRANCH_SUMMARY_SCHEMA =
-  githubResourceSchema<GitHubBranchSummary>(GITHUB_BRANCH_BASE_SCHEMA)
-export const GITHUB_REFERENCE_SCHEMA = githubResourceSchema<GitHubReference>(
-  GITHUB_REFERENCE_BASE_SCHEMA,
-)
-export const GITHUB_WORKFLOW_SCHEMA = githubResourceSchema<GitHubWorkflow>(
-  GITHUB_WORKFLOW_BASE_SCHEMA,
-)
+  githubRestResourceSchema<GitHubBranchSummary>("branch-summary")
+export const GITHUB_REFERENCE_SCHEMA =
+  githubRestResourceSchema<GitHubReference>("reference")
+export const GITHUB_WORKFLOW_SCHEMA =
+  githubRestResourceSchema<GitHubWorkflow>("workflow")
 export const GITHUB_WORKFLOW_RUN_SCHEMA =
-  githubResourceSchema<GitHubWorkflowRun>(GITHUB_WORKFLOW_RUN_BASE_SCHEMA)
+  githubRestResourceSchema<GitHubWorkflowRun>("workflow-run")
 export const GITHUB_WORKFLOW_JOB_SCHEMA =
-  githubResourceSchema<GitHubWorkflowJob>(GITHUB_WORKFLOW_JOB_BASE_SCHEMA)
+  githubRestResourceSchema<GitHubWorkflowJob>("workflow-job")
 export const GITHUB_PULL_REQUEST_FILE_SCHEMA =
-  githubResourceSchema<GitHubPullRequestFile>(
-    GITHUB_PULL_REQUEST_FILE_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubPullRequestFile>("pull-request-file")
 export const GITHUB_PULL_REQUEST_REVIEW_RESOURCE_SCHEMA =
-  githubResourceSchema<GitHubPullRequestReview>(
-    GITHUB_PULL_REQUEST_REVIEW_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubPullRequestReview>("pull-request-review")
 export const GITHUB_PULL_REQUEST_REVIEW_REQUEST_SCHEMA =
-  githubResourceSchema<GitHubPullRequestReviewRequest>(
-    GITHUB_PULL_REQUEST_REVIEW_BASE_SCHEMA,
+  githubRestResourceSchema<GitHubPullRequestReviewRequest>(
+    "pull-request-review-request",
   )
 export const GITHUB_PULL_REQUEST_REVIEW_COMMENT_SCHEMA =
-  githubResourceSchema<GitHubPullRequestReviewComment>(
-    GITHUB_PULL_REQUEST_REVIEW_COMMENT_BASE_SCHEMA,
+  githubRestResourceSchema<GitHubPullRequestReviewComment>(
+    "pull-request-review-comment",
   )
 export const GITHUB_PULL_REQUEST_BRANCH_UPDATE_SCHEMA =
-  githubResourceSchema<GitHubPullRequestBranchUpdate>(
-    GITHUB_PULL_REQUEST_BRANCH_UPDATE_BASE_SCHEMA,
+  githubRestResourceSchema<GitHubPullRequestBranchUpdate>(
+    "pull-request-branch-update",
   )
-export const GITHUB_RELEASE_SCHEMA = githubResourceSchema<GitHubRelease>(
-  GITHUB_RELEASE_BASE_SCHEMA,
-)
+export const GITHUB_RELEASE_SCHEMA =
+  githubRestResourceSchema<GitHubRelease>("release")
 export const GITHUB_RELEASE_ASSET_SCHEMA =
-  githubResourceSchema<GitHubReleaseAsset>(GITHUB_RELEASE_ASSET_BASE_SCHEMA)
-export const GITHUB_DEPLOYMENT_SCHEMA = githubResourceSchema<GitHubDeployment>(
-  GITHUB_DEPLOYMENT_BASE_SCHEMA,
-)
+  githubRestResourceSchema<GitHubReleaseAsset>("release-asset")
+export const GITHUB_DEPLOYMENT_SCHEMA =
+  githubRestResourceSchema<GitHubDeployment>("deployment")
 export const GITHUB_DEPLOYMENT_CREATION_SCHEMA =
-  githubResourceSchema<GitHubDeploymentCreation>(
-    GITHUB_DEPLOYMENT_CREATION_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubDeploymentCreation>("deployment-creation")
 export const GITHUB_DEPLOYMENT_STATUS_SCHEMA =
-  githubResourceSchema<GitHubDeploymentStatus>(
-    GITHUB_DEPLOYMENT_STATUS_BASE_SCHEMA,
-  )
+  githubRestResourceSchema<GitHubDeploymentStatus>("deployment-status")
 export const GITHUB_COMMIT_STATUS_SCHEMA =
-  githubResourceSchema<GitHubCommitStatus>(GITHUB_COMMIT_STATUS_BASE_SCHEMA)
-export const GITHUB_CHECK_RUN_SCHEMA = githubResourceSchema<GitHubCheckRun>(
-  GITHUB_CHECK_RUN_BASE_SCHEMA,
-)
+  githubRestResourceSchema<GitHubCommitStatus>("commit-status")
+export const GITHUB_CHECK_RUN_SCHEMA =
+  githubRestResourceSchema<GitHubCheckRun>("check-run")
 export const GITHUB_COMBINED_COMMIT_STATUS_SCHEMA =
-  githubResourceSchema<GitHubCombinedCommitStatus>(
-    z.looseObject({
-      sha: z.string(),
-      state: z.string(),
-      statuses: GITHUB_COMMIT_STATUS_BASE_SCHEMA.array(),
-      total_count: z.number().int().nonnegative(),
-    }),
-  )
-export const GITHUB_WORKFLOW_DISPATCH_RESULT_SCHEMA: z.ZodType<GitHubWorkflowDispatchResult> =
-  z.object({
-    html_url: z.string(),
-    run_url: z.string(),
-    workflow_run_id: z.number().int().positive(),
-  })
+  githubRestResourceSchema<GitHubCombinedCommitStatus>("combined-commit-status")
+export const GITHUB_WORKFLOW_DISPATCH_RESULT_SCHEMA = z.preprocess(
+  normalizeGitHubJsonResponse,
+  githubRestResourceSchema<GitHubWorkflowDispatchResult>("workflow-dispatch"),
+)
 export const GITHUB_EMPTY_RESPONSE_SCHEMA = z.object({})
 
 /**
- * Validates a provider resource while preserving its official Octokit type.
+ * Octokit returns text when GitHub omits or mislabels the JSON content type.
+ * Leave malformed text untouched so output validation fails terminally outside
+ * the action handler instead of throwing a retryable post-side-effect error.
  *
- * @param schema - Runtime schema for the resource's stable fields.
+ * @param value - Octokit response data.
  */
-function githubResourceSchema<T>(schema: z.ZodType): z.ZodType<T> {
-  return z.custom<T>((value) => schema.safeParse(value).success)
+function normalizeGitHubJsonResponse(value: unknown): unknown {
+  if (typeof value !== "string") return value
+  try {
+    const parsed: unknown = JSON.parse(value)
+    return parsed
+  } catch {
+    return value
+  }
 }