GitHub issues and Actions events

/**
 * Private, editor-run GitHub reader. Install separately from the web receiver.
 * @typedef {{repository: string, issueNumber: number, token: string}} GitHubPracticeConfig
 */
const GITHUB_API_VERSION = '2026-03-10';
const GITHUB_MAX_RESPONSE_BYTES = 65536;

/** Check local configuration shape without sending a request. @returns {void} */
function checkGitHubReaderSetup() {
  readGitHubPracticeConfig_();
  console.log('GitHub reader configuration shape checked; no request sent.');
}

/**
 * Read one configured private repository and one issue; never mutate GitHub.
 * @returns {void}
 */
function readGitHubPracticeIssue() {
  const deadline = Date.now() + 25000;
  const config = readGitHubPracticeConfig_();
  const path = '/repos/' + config.repository.split('/').map(encodeURIComponent).join('/');
  const repository = getGitHubObject_(path, config.token, deadline);
  if (repository.private !== true || repository.fork !== false || repository.archived !== false ||
      typeof repository.id !== 'number' || !Number.isSafeInteger(repository.id) || repository.id <= 0 ||
      typeof repository.full_name !== 'string' ||
      repository.full_name.toLowerCase() !== config.repository.toLowerCase()) {
    throw new Error('GH_EXPECTED_PRIVATE_UNARCHIVED_PRACTICE_REPOSITORY');
  }
  const issue = getGitHubObject_(path + '/issues/' + config.issueNumber, config.token, deadline);
  if (issue.number !== config.issueNumber || 'pull_request' in issue ||
      issue.repository_url !== 'https://api.github.com/repos/' + repository.full_name ||
      (issue.state !== 'open' && issue.state !== 'closed') ||
      typeof issue.title !== 'string' || issue.title.length === 0 || issue.title.length > 160 ||
      typeof issue.comments !== 'number' || !Number.isSafeInteger(issue.comments) || issue.comments < 0 ||
      typeof issue.updated_at !== 'string' || issue.updated_at.length > 40 ||
      !Number.isFinite(Date.parse(issue.updated_at))) {
    throw new Error('GH_UNEXPECTED_PRACTICE_ISSUE');
  }
  // No title/body/author/response/headers/token in the output.
  console.log(JSON.stringify({
    repositoryId: repository.id,
    issueNumber: issue.number,
    state: issue.state,
    titleCharacters: issue.title.length,
    comments: issue.comments,
    updatedAt: issue.updated_at,
  }));
}

/** @returns {GitHubPracticeConfig} */
function readGitHubPracticeConfig_() {
  const store = PropertiesService.getScriptProperties();
  const repository = store.getProperty('GITHUB_PRACTICE_REPOSITORY');
  const issueText = store.getProperty('GITHUB_PRACTICE_ISSUE_NUMBER');
  const token = store.getProperty('GITHUB_PRACTICE_PAT');
  if (typeof repository !== 'string' ||
      !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(repository) ||
      typeof issueText !== 'string' || !/^[1-9][0-9]{0,9}$/.test(issueText) ||
      typeof token !== 'string' || token.length < 20 || token.length > 255 ||
      !/^[A-Za-z0-9_]+$/.test(token)) {
    throw new Error('GH_CONFIG_REQUIRED: set the three documented Script Properties without whitespace.');
  }
  // Token syntax is only a local guard; it cannot prove type, grant, expiry or ownership.
  return {repository: repository, issueNumber: Number(issueText), token: token};
}

/**
 * Fixed-origin, no-redirect GET. The two reads share a deadline; no automatic retry.
 * @param {string} path Constructed path, never an API response or event URL.
 * @param {string} token The approved fine-grained personal token.
 * @param {number} deadline Absolute millisecond deadline including earlier work.
 * @returns {Record<string, unknown>}
 */
function getGitHubObject_(path, token, deadline) {
  const seconds = Math.floor((deadline - Date.now()) / 1000);
  if (seconds < 1) throw new Error('GH_READ_DEADLINE');
  /** @type {ReturnType<typeof UrlFetchApp.fetch>} */
  let response;
  try {
    response = UrlFetchApp.fetch('https://api.github.com' + path, {
      method: 'get',
      headers: {
        Accept: 'application/vnd.github+json',
        Authorization: 'Bearer ' + token,
        'X-GitHub-Api-Version': GITHUB_API_VERSION,
        'User-Agent': 'apps-script-private-issue-practice',
      },
      followRedirects: false,
      muteHttpExceptions: true,
      validateHttpsCertificates: true,
      timeoutSeconds: seconds,
    });
  } catch (error) {
    throw new Error('GH_READ_TRANSPORT_FAILED: no receipt was sent; inspect before another read.');
  }
  if (Date.now() > deadline) throw new Error('GH_READ_DEADLINE');
  const status = response.getResponseCode();
  const headers = githubRecord_(response.getAllHeaders());
  if (status !== 200) {
    const remaining = githubHeader_(headers, 'x-ratelimit-remaining');
    const retryAfter = githubHeader_(headers, 'retry-after');
    const reset = githubHeader_(headers, 'x-ratelimit-reset');
    console.error(JSON.stringify({
      stage: 'github_read', status: status,
      remaining: boundedDecimalHeader_(remaining),
      retryAfterSeconds: boundedDecimalHeader_(retryAfter),
      resetEpochSeconds: boundedDecimalHeader_(reset),
    }));
    if (status >= 300 && status < 400) throw new Error('GH_REDIRECT_OR_UNEXPECTED_CACHE_RESPONSE: recheck the configured identity.');
    if (status === 401) throw new Error('GH_TOKEN_REJECTED: inspect expiry or revocation; do not print the token.');
    if (status === 403 || status === 429) throw new Error('GH_PERMISSION_OR_RATE_LIMIT: inspect grant/policy and rate headers; do not loop.');
    if (status === 404) throw new Error('GH_NOT_FOUND_OR_NOT_AUTHORIZED: a private resource can be concealed.');
    if (status === 410) throw new Error('GH_GONE: inspect the issue and API version.');
    throw new Error('GH_UNEXPECTED_HTTP_STATUS');
  }
  const type = githubHeader_(headers, 'content-type');
  if (type === null || type.split(';')[0].trim().toLowerCase() !== 'application/json') {
    throw new Error('GH_EXPECTED_JSON');
  }
  const text = response.getContentText('UTF-8');
  // UrlFetch has already downloaded the response; this is not a transport byte cap.
  if (text.length === 0 || text.length > GITHUB_MAX_RESPONSE_BYTES ||
      Utilities.newBlob(text).getBytes().length > GITHUB_MAX_RESPONSE_BYTES) {
    throw new Error('GH_RESPONSE_TOO_LARGE_OR_EMPTY');
  }
  /** @type {unknown} */
  let value;
  try { value = JSON.parse(text); }
  catch (error) { throw new Error('GH_INVALID_JSON'); }
  const result = githubRecord_(value);
  if (Date.now() > deadline) throw new Error('GH_READ_DEADLINE');
  return result;
}

/** @param {unknown} value @returns {Record<string, unknown>} */
function githubRecord_(value) {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
    throw new Error('GH_EXPECTED_OBJECT');
  }
  return /** @type {Record<string, unknown>} */ (value);
}

/**
 * @param {Record<string, unknown>} headers
 * @param {string} wanted Lowercase header name.
 * @returns {string | null}
 */
function githubHeader_(headers, wanted) {
  const names = Object.keys(headers).filter((name) => name.toLowerCase() === wanted);
  if (names.length !== 1) return null;
  const value = headers[names[0]];
  return typeof value === 'string' ? value : null;
}

/** @param {string | null} value @returns {string | null} */
function boundedDecimalHeader_(value) {
  return value !== null && /^[0-9]{1,12}$/.test(value) ? value : null;
}

{
  "timeZone": "Etc/UTC",
  "runtimeVersion": "V8",
  "oauthScopes": ["https://www.googleapis.com/auth/script.external_request"]
}

name: Practice issue receipt

on:
  issues:
    types: [edited]
  workflow_dispatch:
    inputs:
      confirm_receipt:
        description: Send one fictional receipt to my approved receiver
        required: true
        default: false
        type: boolean
      repeat_same_envelope:
        description: After confirmation, send the identical envelope once more
        required: true
        default: false
        type: boolean

permissions: {}

jobs:
  receipt:
    if: >-
      github.event.repository.private == true &&
      github.repository == vars.PRACTICE_REPOSITORY &&
      github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
      (github.event_name == 'workflow_dispatch' ||
       format('{0}', github.event.issue.number) == vars.PRACTICE_ISSUE_NUMBER)
    runs-on: ubuntu-24.04
    timeout-minutes: 3
    permissions:
      contents: read
      issues: read
    steps:
      - name: Check out only this event's trusted default-branch commit
        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6, verified official commit
        with:
          ref: ${{ github.sha }}
          fetch-depth: 1
          persist-credentials: false
      - name: Select the exact Node runtime without package caching
        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6, verified official commit
        with:
          node-version: '24.21.0'
          check-latest: false
          package-manager-cache: false
      - name: Deliver the bounded custom receipt
        env:
          PRACTICE_REPOSITORY: ${{ vars.PRACTICE_REPOSITORY }}
          PRACTICE_REPOSITORY_ID: ${{ vars.PRACTICE_REPOSITORY_ID }}
          PRACTICE_ISSUE_NUMBER: ${{ vars.PRACTICE_ISSUE_NUMBER }}
          CONFIRM_RECEIPT: ${{ inputs.confirm_receipt }}
          REPEAT_SAME_ENVELOPE: ${{ inputs.repeat_same_envelope }}
          GH_READ_TOKEN: ${{ github.token }}
          EVENT_ENDPOINT_URL: ${{ secrets.EVENT_ENDPOINT_URL }}
          EVENT_SECRET_HEX: ${{ secrets.EVENT_SECRET_HEX }}
        run: node .github/scripts/send-receipt.mjs

import { Buffer } from 'node:buffer';
import { createHash, createHmac } from 'node:crypto';
import { readFile, stat } from 'node:fs/promises';
import { request } from 'node:https';
import process from 'node:process';
import { clearTimeout, setTimeout } from 'node:timers';
import { URL } from 'node:url';

/** @typedef {{version: number, eventId: string, issuedAt: number, payload: {type: string, requestId: string, note: string}}} ReceiptEvent */
/** @typedef {{status: number, headers: import('node:http').IncomingHttpHeaders, text: string}} HttpResult */
/** @typedef {{eventId: string, acceptedAt: number, expiresAt: number}} Receipt */
/** @typedef {{status: 'accepted' | 'duplicate', receipt: Receipt}} AcceptedReply */
const API_VERSION = '2026-03-10';
const MAX_JSON_BYTES = 65536;
const MAX_RECEIPT_BYTES = 2048;
/** @type {Record<string, boolean>} */
const REJECTIONS = {bad_request: false, unauthorized: false, stale: false, conflict: false, capacity: true, busy: true, unavailable: true};

class PracticeError extends Error {
  /** @param {string} code A fixed local diagnostic, never provider text. */
  constructor(code) { super(code); this.name = 'PracticeError'; }
}

/** @returns {Promise<void>} */
async function main() {
  const deadline = Date.now() + 60000;
  if (process.env.GITHUB_ACTIONS !== 'true' || process.env.GITHUB_SERVER_URL !== 'https://github.com' ||
      process.env.GITHUB_API_URL !== 'https://api.github.com') throw new PracticeError('EXPECTED_GITHUB_COM_RUNNER');
  if (process.env.GITHUB_RUN_ATTEMPT !== '1') throw new PracticeError('RERUN_BLOCKED_RECONCILE_ORIGINAL_RUN');
  const repository = requiredEnv('PRACTICE_REPOSITORY');
  const repositoryId = decimalEnv('PRACTICE_REPOSITORY_ID');
  const issueNumber = Number(decimalEnv('PRACTICE_ISSUE_NUMBER', 10));
  const runId = decimalEnv('GITHUB_RUN_ID');
  if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(repository) ||
      repository !== process.env.GITHUB_REPOSITORY || repositoryId !== process.env.GITHUB_REPOSITORY_ID) {
    throw new PracticeError('WRONG_CONFIGURED_REPOSITORY');
  }
  const eventPath = requiredEnv('GITHUB_EVENT_PATH');
  const info = await stat(eventPath);
  if (!info.isFile() || info.size === 0 || info.size > MAX_JSON_BYTES) throw new PracticeError('EVENT_FILE_TOO_LARGE_OR_EMPTY');
  const bytes = await readFile(eventPath);
  if (bytes.length > MAX_JSON_BYTES) throw new PracticeError('EVENT_FILE_TOO_LARGE');
  const native = parseObject(bytes.toString('utf8'));
  const nativeRepo = record(native.repository);
  if (nativeRepo.private !== true || nativeRepo.fork !== false ||
      typeof nativeRepo.id !== 'number' || !Number.isSafeInteger(nativeRepo.id) || nativeRepo.id <= 0 ||
      String(nativeRepo.id) !== repositoryId || nativeRepo.full_name !== repository ||
      typeof nativeRepo.default_branch !== 'string' ||
      process.env.GITHUB_REF !== 'refs/heads/' + nativeRepo.default_branch) {
    throw new PracticeError('EXPECTED_PRIVATE_DEFAULT_BRANCH_EVENT');
  }
  const eventName = requiredEnv('GITHUB_EVENT_NAME');
  /** @type {Record<string, unknown>} */
  let issue;
  /** @type {string} */
  let kind;
  let repeat = false;
  if (eventName === 'issues') {
    if (native.action !== 'edited') throw new PracticeError('UNSUPPORTED_ISSUE_ACTION');
    issue = record(native.issue);
    if (issue.number !== issueNumber) {
      console.log(JSON.stringify({stage: 'skipped', reason: 'different_issue'}));
      return;
    }
    kind = 'issues.edited';
  } else if (eventName === 'workflow_dispatch') {
    if (process.env.CONFIRM_RECEIPT !== 'true') throw new PracticeError('MANUAL_SEND_NOT_CONFIRMED');
    repeat = process.env.REPEAT_SAME_ENVELOPE === 'true';
    const token = requiredEnv('GH_READ_TOKEN');
    if (!/^[A-Za-z0-9_]{20,255}$/.test(token)) throw new PracticeError('MISSING_JOB_TOKEN');
    const path = repository.split('/').map(encodeURIComponent).join('/');
    const response = await requestOnce(new URL('https://api.github.com/repos/' + path + '/issues/' + issueNumber),
      'GET', {Accept: 'application/vnd.github+json', Authorization: 'Bearer ' + token,
        'X-GitHub-Api-Version': API_VERSION, 'User-Agent': 'apps-script-receipt-practice'}, '', MAX_JSON_BYTES, deadline);
    if (response.status !== 200) {
      console.error(JSON.stringify({stage: 'github_read', status: response.status,
        remaining: decimalHeader(response.headers['x-ratelimit-remaining']),
        retryAfterSeconds: decimalHeader(response.headers['retry-after']),
        resetEpochSeconds: decimalHeader(response.headers['x-ratelimit-reset'])}));
      throw new PracticeError('GITHUB_READ_REJECTED_NO_RECEIPT_SENT');
    }
    requireJson(response);
    issue = parseObject(response.text);
    kind = 'workflow_dispatch';
  } else {
    throw new PracticeError('UNSUPPORTED_NATIVE_EVENT');
  }
  if (issue.number !== issueNumber || 'pull_request' in issue ||
      issue.repository_url !== 'https://api.github.com/repos/' + repository ||
      (issue.state !== 'open' && issue.state !== 'closed') ||
      typeof issue.title !== 'string' || issue.title.length === 0 || issue.title.length > 160) {
    throw new PracticeError('UNEXPECTED_PRACTICE_ISSUE');
  }
  const endpoint = requiredEnv('EVENT_ENDPOINT_URL');
  const secret = requiredEnv('EVENT_SECRET_HEX');
  if (!/^https:\/\/script\.google\.com\/macros\/s\/[A-Za-z0-9_-]{20,200}\/exec$/.test(endpoint) ||
      !/^[0-9a-f]{64}$/.test(secret)) throw new PracticeError('RECEIVER_CONFIGURATION_INVALID');
  // SHA-256 truncation gives a stable UUID-shaped protocol ID for this repository/run.
  // It is not GitHub's X-GitHub-Delivery ID or a claim of UUIDv4 randomness.
  const hex = createHash('sha256').update(JSON.stringify(['github-practice-receipt-v1', repositoryId, runId]), 'utf8').digest('hex').slice(0, 32);
  const eventId = [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20)].join('-');
  const note = 'GitHub ' + kind + ' #' + issueNumber + ' ' + issue.state +
    ' titleChars=' + issue.title.length + ' run=' + runId;
  if (note.length > 120 || Buffer.byteLength(note, 'utf8') > 240 || /[\u0000-\u001f\u007f]/.test(note)) {
    throw new PracticeError('NOTE_EXCEEDS_FROZEN_PROTOCOL');
  }
  /** @type {ReceiptEvent} */
  const event = {version: 1, eventId, issuedAt: Date.now(), payload: {type: 'request.note', requestId: 'REQ-001', note}};
  const canonical = JSON.stringify(['apps-script-custom-event', event.version, event.eventId, event.issuedAt,
    event.payload.type, event.payload.requestId, event.payload.note]);
  // EXACT receiver rule: the 64 hex characters are UTF-8 key text, not decoded bytes.
  const signature = createHmac('sha256', Buffer.from(secret, 'utf8')).update(canonical, 'utf8').digest('hex');
  const body = JSON.stringify({...event, signature});
  if (Buffer.byteLength(body, 'utf8') > MAX_RECEIPT_BYTES) throw new PracticeError('ENVELOPE_TOO_LARGE');
  if (Date.now() >= deadline) throw new PracticeError('PREPARATION_DEADLINE_NO_DISPATCH');
  // Safe reconciliation identifiers before dispatch. Never log body, MAC, URL or secret.
  console.log(JSON.stringify({stage: 'dispatch_possible', runId, eventId, issuedAt: event.issuedAt,
    requestId: event.payload.requestId, kind, issueNumber, state: issue.state, titleCharacters: issue.title.length}));
  const first = await postReceipt(endpoint, body, event, deadline);
  console.log(JSON.stringify({stage: 'receipt', ...first}));
  if (repeat) {
    // An explicit duplicate exercise AFTER a valid receipt, not failure retry.
    const second = await postReceipt(endpoint, body, event, deadline);
    if (second.status !== 'duplicate' || second.receipt.acceptedAt !== first.receipt.acceptedAt ||
        second.receipt.expiresAt !== first.receipt.expiresAt) throw new PracticeError('DUPLICATE_RECEIPT_CHANGED');
    console.log(JSON.stringify({stage: 'same_envelope_repeat', ...second}));
  }
}

/**
 * One POST, optionally one Google ContentService GET redirect, never a POST redirect.
 * @param {string} endpoint
 * @param {string} body
 * @param {ReceiptEvent} event
 * @param {number} deadline
 * @returns {Promise<AcceptedReply>}
 */
async function postReceipt(endpoint, body, event, deadline) {
  let response = await requestOnce(new URL(endpoint), 'POST', {
    Accept: 'application/json', 'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': String(Buffer.byteLength(body, 'utf8')),
  }, body, MAX_RECEIPT_BYTES, deadline);
  if (response.status === 302 || response.status === 303) {
    const location = response.headers.location;
    if (typeof location !== 'string' || location.length > 4096) throw new PracticeError('RECEIPT_REDIRECT_UNKNOWN');
    const target = new URL(location);
    if (target.protocol !== 'https:' || target.hostname !== 'script.googleusercontent.com' ||
        target.port !== '' || target.username !== '' || target.password !== '' || target.hash !== '') {
      throw new PracticeError('RECEIPT_REDIRECT_NOT_ALLOWED');
    }
    response = await requestOnce(target, 'GET', {Accept: 'application/json'}, '', MAX_RECEIPT_BYTES, deadline);
  }
  if (response.status !== 200) throw new PracticeError('RECEIPT_HTTP_UNKNOWN');
  requireJson(response);
  const value = parseObject(response.text);
  if (value.protocol === 1 && value.ok === false && exactKeys(value, ['protocol', 'ok', 'code', 'retryable']) &&
      typeof value.code === 'string' && Object.hasOwn(REJECTIONS, value.code) && value.retryable === REJECTIONS[value.code]) {
    console.error(JSON.stringify({stage: 'receiver_rejection', code: value.code, retryable: value.retryable, eventId: event.eventId}));
    throw new PracticeError('RECEIVER_REJECTED_RECONCILE_BEFORE_NEW_RUN');
  }
  if (value.protocol !== 1 || value.ok !== true || !exactKeys(value, ['protocol', 'ok', 'status', 'receipt']) ||
      (value.status !== 'accepted' && value.status !== 'duplicate')) throw new PracticeError('RECEIPT_ENVELOPE_UNKNOWN');
  const receipt = record(value.receipt);
  if (!exactKeys(receipt, ['eventId', 'acceptedAt', 'expiresAt']) || receipt.eventId !== event.eventId ||
      typeof receipt.acceptedAt !== 'number' || !Number.isSafeInteger(receipt.acceptedAt) || receipt.acceptedAt <= 0 ||
      typeof receipt.expiresAt !== 'number' || !Number.isSafeInteger(receipt.expiresAt) ||
      receipt.expiresAt !== receipt.acceptedAt + 86400000 ||
      receipt.acceptedAt - event.issuedAt > 300000 || event.issuedAt - receipt.acceptedAt > 30000) {
    throw new PracticeError('RECEIPT_ID_OR_TIMESTAMPS_UNKNOWN');
  }
  if (Date.now() > deadline) throw new PracticeError('RECEIPT_DEADLINE_RECONCILE');
  return {status: value.status, receipt: {eventId: event.eventId, acceptedAt: receipt.acceptedAt, expiresAt: receipt.expiresAt}};
}

/**
 * TLS verification stays enabled. Node HTTPS does not automatically follow redirects.
 * Timeout includes connection and body consumption; chunks are counted before retaining.
 * @param {URL} url
 * @param {'GET' | 'POST'} method
 * @param {Record<string, string>} headers
 * @param {string} body
 * @param {number} maxBytes
 * @param {number} deadline
 * @returns {Promise<HttpResult>}
 */
function requestOnce(url, method, headers, body, maxBytes, deadline) {
  const remaining = Math.min(25000, deadline - Date.now());
  if (remaining < 1) return Promise.reject(new PracticeError('HTTP_DEADLINE'));
  return new Promise((resolve, reject) => {
    const req = request(url, {method, headers, agent: false}, (res) => {
      /** @type {Buffer[]} */
      const chunks = [];
      let length = 0;
      res.on('data', (/** @type {unknown} */ chunk) => {
        if (!Buffer.isBuffer(chunk)) { res.destroy(new PracticeError('HTTP_UNEXPECTED_CHUNK')); return; }
        length += chunk.length;
        if (length > maxBytes) { res.destroy(new PracticeError('HTTP_RESPONSE_TOO_LARGE')); return; }
        chunks.push(chunk);
      });
      res.on('error', () => reject(new PracticeError('HTTP_BODY_FAILED')));
      res.on('end', () => {
        clearTimeout(timer);
        if (!res.complete) { reject(new PracticeError('HTTP_BODY_INCOMPLETE')); return; }
        resolve({status: res.statusCode ?? 0, headers: res.headers, text: Buffer.concat(chunks, length).toString('utf8')});
      });
      res.on('close', () => {
        clearTimeout(timer);
        if (!res.complete) reject(new PracticeError('HTTP_BODY_INCOMPLETE'));
      });
    });
    const timer = setTimeout(() => req.destroy(new PracticeError('HTTP_DEADLINE')), remaining);
    req.on('error', () => { clearTimeout(timer); reject(new PracticeError('HTTP_TRANSPORT_FAILED')); });
    req.end(body);
  });
}

/** @param {HttpResult} response @returns {void} */
function requireJson(response) {
  const type = response.headers['content-type'];
  if (typeof type !== 'string' || type.split(';')[0].trim().toLowerCase() !== 'application/json') {
    throw new PracticeError('EXPECTED_JSON_NOT_LOGIN_PAGE');
  }
}

/** @param {unknown} value @returns {Record<string, unknown>} */
function record(value) {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new PracticeError('EXPECTED_OBJECT');
  return /** @type {Record<string, unknown>} */ (value);
}

/** @param {string} text @returns {Record<string, unknown>} */
function parseObject(text) {
  /** @type {unknown} */
  let value;
  try { value = JSON.parse(text); }
  catch { throw new PracticeError('INVALID_JSON'); }
  return record(value);
}

/** @param {Record<string, unknown>} value @param {string[]} keys @returns {boolean} */
function exactKeys(value, keys) {
  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
}

/** @param {string} name @returns {string} */
function requiredEnv(name) {
  const value = process.env[name];
  if (typeof value !== 'string' || value.length === 0) throw new PracticeError('MISSING_CONFIGURATION');
  return value;
}

/** @param {string} name @param {number} [maxDigits] @returns {string} */
function decimalEnv(name, maxDigits = 20) {
  const value = requiredEnv(name);
  if (!/^[1-9][0-9]*$/.test(value) || value.length > maxDigits) throw new PracticeError('INVALID_NUMERIC_ID');
  return value;
}

/** @param {unknown} value @returns {string | null} */
function decimalHeader(value) {
  return typeof value === 'string' && /^[0-9]{1,12}$/.test(value) ? value : null;
}

main().catch((/** @type {unknown} */ error) => {
  console.error(JSON.stringify({stage: 'stopped', code: error instanceof PracticeError ? error.message : 'UNEXPECTED_FAILURE',
    instruction: 'If dispatch_possible appeared, acceptance can be unknown. Inspect the original run and receiver; do not rerun.'}));
  process.exitCode = 1;
});

{
  "purpose": "Fictional content to enter manually in one approved disposable private repository. This file is not executed, posted by the sender, or a captured GitHub response.",
  "repositoryName": "apps-script-github-practice",
  "title": "Review fictional workshop map",
  "body": "Practice issue only. Check the fictional workshop map labels. No real customer, project, credential, or personal information belongs here.",
  "changedTitle": "Review fictional workshop map (checked)",
  "restoredTitle": "Review fictional workshop map",
  "issueNumber": "Use the actual issue number shown in the new issue URL; never assume it is 1.",
  "receiptRequestId": "REQ-001",
  "mapping": "REQ-001 is this lesson's one local receipt record key. It is not the GitHub issue number, repository ID, workflow run ID or webhook delivery ID."
}

{
  "purpose": "A human setup worksheet, not an importable API payload. Do not replace these instructions with live tokens, URLs, accounts or repository identifiers in the example source.",
  "appsScriptReader": {
    "projectName": "GitHub private issue reader",
    "install": ["Code.gs", "appsscript.json"],
    "scriptProperties": {
      "GITHUB_PRACTICE_REPOSITORY": "Exact owner/apps-script-github-practice from the approved private repository, without a URL prefix or trailing slash",
      "GITHUB_PRACTICE_ISSUE_NUMBER": "Actual positive issue number, at most 10 digits, from the new fictional issue's URL",
      "GITHUB_PRACTICE_PAT": "New short-lived fine-grained personal access token: only the selected practice repository, Issues read-only, automatic Metadata read-only, no other permissions"
    },
    "deployment": "None. Keep the reader private and use editor entrypoints only. Never put this PAT in the receiver or Actions."
  },
  "receiver": {
    "canonicalExampleId": "http-endpoints-webhooks",
    "install": "Use the existing receiver's complete Code.gs, Protocol.gs and manifest unchanged in its own isolated project. Do not copy them into this GitHub example or combine with its reader.",
    "scriptProperty": "EVENT_SECRET_HEX: one new 32-byte random secret encoded as exactly 64 lowercase hex characters, generated by the approved receiver setup procedure",
    "deployment": "Approved versioned web app, execute as deployer, Anyone/anonymous access permitted by account policy, canonical https://script.google.com/macros/s/deployment-ID/exec URL. No secrets in query parameters.",
    "precondition": "Run checkReceiverSetup in that project, confirm no unresolved prior events and sufficient room in its eight-receipt/24-hour ledger. Local shape/liveness checks are not deployment/auth/receipt proof."
  },
  "githubRepository": {
    "requiredVisibility": "private; new non-fork repository controlled by the approved owner",
    "defaultBranchFiles": {
      ".github/scripts/send-receipt.mjs": "Install the complete supplied send-receipt.mjs here first",
      ".github/workflows/practice-issue-receipt.yml": "Install the complete supplied receipt-workflow.yml here last"
    },
    "actionsVariables": {
      "PRACTICE_REPOSITORY": "Exact case-matching owner/repo shown by GitHub for this repository",
      "PRACTICE_REPOSITORY_ID": "Numeric repositoryId observed in the private Apps Script reader output; enter as decimal text",
      "PRACTICE_ISSUE_NUMBER": "Same actual decimal issue number configured in the reader"
    },
    "actionsRepositorySecrets": {
      "EVENT_ENDPOINT_URL": "Canonical approved receiver /exec URL; keep it out of source/logs even though it is not the HMAC credential",
      "EVENT_SECRET_HEX": "Exact same 64-character secret text stored in the receiver, without surrounding quotes or newline"
    },
    "automaticJobToken": "GitHub supplies github.token. This workflow grants only contents:read and issues:read; never create a repository secret named GITHUB_TOKEN or substitute the PAT.",
    "billing": "Obtain owner approval for standard GitHub-hosted Linux minutes in a private repository. Inspect remaining allowance and spend controls; no promise of free execution. No larger/self-hosted runner, matrix, schedule, cache, artifact upload, dependency install or paid fallback.",
    "start": "Actions > Practice issue receipt > Run workflow on the default branch, confirm_receipt true. repeat_same_envelope is an optional deliberate post-confirmation duplicate demonstration, not a failure retry.",
    "nativeChange": "Edit the configured fictional issue title once after the workflow is installed. Only issues.edited is selected; opening, commenting on or closing it is not this workflow's trigger.",
    "rerun": "The sender refuses GITHUB_RUN_ATTEMPT other than 1. Do not use Re-run jobs after unknown delivery. Reconcile the original run ID/event ID before approving a distinct new dispatch."
  }
}