appstore-tools 1.0.0

package/dist/cli.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { AppStoreConnectClient, InfrastructureError } from "./api/client.js";
+import { appsListCommand } from "./commands/apps-list.js";
+import { buildsUploadCommand } from "./commands/builds-upload.js";
+import { ipaGenerateCommand } from "./commands/ipa-generate.js";
+const DEFAULT_BASE_URL = "https://api.appstoreconnect.apple.com/";
+export async function resolveCliEnvironment(env) {
+    const issuerId = env.ASC_ISSUER_ID?.trim();
+    const keyId = env.ASC_KEY_ID?.trim();
+    const privateKeyPath = env.ASC_PRIVATE_KEY_PATH?.trim();
+    const privateKeyRaw = env.ASC_PRIVATE_KEY?.trim();
+    const baseUrl = env.ASC_BASE_URL?.trim() || DEFAULT_BASE_URL;
+    const missingKeys = [];
+    if (!issuerId) {
+        missingKeys.push("ASC_ISSUER_ID");
+    }
+    if (!keyId) {
+        missingKeys.push("ASC_KEY_ID");
+    }
+    if (!privateKeyPath && !privateKeyRaw) {
+        missingKeys.push("ASC_PRIVATE_KEY or ASC_PRIVATE_KEY_PATH");
+    }
+    if (missingKeys.length > 0) {
+        throw new InfrastructureError(`Missing required environment variables: ${missingKeys.join(", ")}`);
+    }
+    const privateKey = privateKeyPath
+        ? await readPrivateKeyFile(privateKeyPath)
+        : normalizePrivateKey(privateKeyRaw);
+    return {
+        issuerId: issuerId,
+        keyId: keyId,
+        privateKey,
+        baseUrl
+    };
+}
+async function readPrivateKeyFile(filePath) {
+    try {
+        return (await readFile(filePath, "utf-8")).trim();
+    }
+    catch (error) {
+        throw new InfrastructureError(`Failed to read private key file at "${filePath}".`, error);
+    }
+}
+function normalizePrivateKey(rawValue) {
+    return rawValue.includes("\\n") ? rawValue.replace(/\\n/g, "\n") : rawValue;
+}
+export function parseCliCommand(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        return { kind: "help" };
+    }
+    if (argv.length === 0) {
+        return { kind: "apps-list", json: false };
+    }
+    const [head, next, ...rest] = argv;
+    if (head === "apps" && next === "list") {
+        const flags = parseFlags(rest);
+        return { kind: "apps-list", json: flags.booleans.has("json") };
+    }
+    if (head === "builds" && next === "upload") {
+        const flags = parseFlags(rest);
+        return parseBuildsUploadCommand(flags);
+    }
+    if (head === "ipa" && next === "generate") {
+        const flags = parseFlags(rest);
+        return parseIpaGenerateCommand(flags);
+    }
+    throw new InfrastructureError(`Unknown command: ${argv.join(" ")}`);
+}
+function parseBuildsUploadCommand(flags) {
+    const appReference = requireFlag(flags, "app");
+    const version = requireFlag(flags, "version");
+    const buildNumber = requireFlag(flags, "build-number");
+    const ipaSource = parseIpaSource(flags, false);
+    return {
+        kind: "builds-upload",
+        json: flags.booleans.has("json"),
+        apply: flags.booleans.has("apply"),
+        waitProcessing: flags.booleans.has("wait-processing"),
+        appReference,
+        version,
+        buildNumber,
+        ipaSource
+    };
+}
+function parseIpaGenerateCommand(flags) {
+    const outputIpaPath = requireFlag(flags, "output-ipa");
+    const ipaSource = parseIpaSource(flags, true);
+    if (ipaSource.kind === "prebuilt") {
+        throw new InfrastructureError("ipa generate does not support --ipa prebuilt input.");
+    }
+    return {
+        kind: "ipa-generate",
+        json: flags.booleans.has("json"),
+        outputIpaPath,
+        ipaSource
+    };
+}
+function parseIpaSource(flags, isGenerateCommand) {
+    const ipaPath = flags.values.ipa;
+    const hasIpa = Boolean(ipaPath);
+    const hasBuildCommand = Boolean(flags.values["build-command"]);
+    const hasGeneratedIpaPath = Boolean(flags.values["generated-ipa-path"]);
+    const hasCustomCommandInputs = hasBuildCommand || hasGeneratedIpaPath;
+    const hasScheme = Boolean(flags.values.scheme);
+    const hasExportOptionsPlist = Boolean(flags.values["export-options-plist"]);
+    const hasWorkspacePath = Boolean(flags.values["workspace-path"]);
+    const hasProjectPath = Boolean(flags.values["project-path"]);
+    const hasXcodebuildInputs = hasScheme ||
+        hasExportOptionsPlist ||
+        hasWorkspacePath ||
+        hasProjectPath ||
+        Boolean(flags.values.configuration) ||
+        Boolean(flags.values["archive-path"]) ||
+        Boolean(flags.values["derived-data-path"]);
+    const sourceModes = [hasIpa, hasCustomCommandInputs, hasXcodebuildInputs].filter(Boolean)
+        .length;
+    if (sourceModes !== 1) {
+        throw new InfrastructureError("Exactly one IPA source mode is required: --ipa, xcodebuild options, or custom command options.");
+    }
+    if (hasIpa) {
+        if (hasCustomCommandInputs || hasXcodebuildInputs) {
+            throw new InfrastructureError("--ipa cannot be combined with generation options (--scheme/--build-command/etc).");
+        }
+        return {
+            kind: "prebuilt",
+            ipaPath: ipaPath
+        };
+    }
+    if (hasCustomCommandInputs) {
+        const buildCommand = requireFlag(flags, "build-command");
+        const generatedIpaPath = requireFlag(flags, "generated-ipa-path");
+        const outputIpaPath = isGenerateCommand ? requireFlag(flags, "output-ipa") : null;
+        return {
+            kind: "customCommand",
+            buildCommand,
+            generatedIpaPath,
+            ...(outputIpaPath ? { outputIpaPath } : {})
+        };
+    }
+    const scheme = requireFlag(flags, "scheme");
+    const exportOptionsPlist = requireFlag(flags, "export-options-plist");
+    if (hasWorkspacePath === hasProjectPath) {
+        throw new InfrastructureError("Exactly one of --workspace-path or --project-path is required for xcodebuild mode.");
+    }
+    const outputIpaPath = isGenerateCommand
+        ? requireFlag(flags, "output-ipa")
+        : flags.values["output-ipa"];
+    return {
+        kind: "xcodebuild",
+        scheme,
+        exportOptionsPlist,
+        ...(flags.values["workspace-path"] ? { workspacePath: flags.values["workspace-path"] } : {}),
+        ...(flags.values["project-path"] ? { projectPath: flags.values["project-path"] } : {}),
+        ...(flags.values.configuration ? { configuration: flags.values.configuration } : {}),
+        ...(flags.values["archive-path"] ? { archivePath: flags.values["archive-path"] } : {}),
+        ...(flags.values["derived-data-path"]
+            ? { derivedDataPath: flags.values["derived-data-path"] }
+            : {}),
+        ...(outputIpaPath ? { outputIpaPath } : {})
+    };
+}
+function parseFlags(argv) {
+    const values = {};
+    const booleans = new Set();
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token) {
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            positionals.push(token);
+            continue;
+        }
+        const tokenWithoutPrefix = token.slice(2);
+        const equalIndex = tokenWithoutPrefix.indexOf("=");
+        const rawFlag = equalIndex >= 0
+            ? tokenWithoutPrefix.slice(0, equalIndex)
+            : tokenWithoutPrefix;
+        const rawValue = equalIndex >= 0 ? tokenWithoutPrefix.slice(equalIndex + 1) : undefined;
+        const flag = rawFlag.trim();
+        if (!flag) {
+            throw new InfrastructureError(`Invalid flag: ${token}`);
+        }
+        if (rawValue !== undefined) {
+            values[flag] = rawValue;
+            continue;
+        }
+        const nextToken = argv[index + 1];
+        if (nextToken && !nextToken.startsWith("--")) {
+            values[flag] = nextToken;
+            index += 1;
+            continue;
+        }
+        booleans.add(flag);
+    }
+    return { positionals, values, booleans };
+}
+function requireFlag(flags, name) {
+    const value = flags.values[name];
+    if (!value || value.trim().length === 0) {
+        throw new InfrastructureError(`Missing required option: --${name}`);
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// CLI options
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.log(`appstore-tools CLI
+
+Usage:
+  appstore-tools --help
+  appstore-tools apps list [--json]
+  appstore-tools ipa generate --output-ipa <path> [xcodebuild/custom options] [--json]
+  appstore-tools builds upload --app <appId|bundleId> --version <x.y.z> --build-number <n> (--ipa <path> | [generation options]) [--wait-processing] [--json] [--apply]
+
+Required environment variables:
+  ASC_ISSUER_ID
+  ASC_KEY_ID
+  ASC_PRIVATE_KEY or ASC_PRIVATE_KEY_PATH
+
+Optional environment variables:
+  ASC_BASE_URL (default: https://api.appstoreconnect.apple.com/)
+
+Generation options (xcodebuild mode):
+  --scheme <name> --export-options-plist <path> (--workspace-path <path> | --project-path <path>)
+  [--configuration <Release>] [--archive-path <path>] [--derived-data-path <path>] [--output-ipa <path>]
+
+Generation options (custom mode):
+  --build-command "<shell command>" --generated-ipa-path <path> [--output-ipa <path>]
+`);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export async function runCli(argv, env) {
+    try {
+        const command = parseCliCommand(argv);
+        return handleCliCommand(command, env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown CLI error";
+        console.error(message);
+        return 1;
+    }
+}
+async function handleCliCommand(command, env) {
+    if (command.kind === "help") {
+        printHelp();
+        return 0;
+    }
+    if (command.kind === "ipa-generate") {
+        return ipaGenerateCommand(command);
+    }
+    const config = await resolveCliEnvironment(env);
+    const client = new AppStoreConnectClient({
+        issuerId: config.issuerId,
+        keyId: config.keyId,
+        privateKey: config.privateKey
+    }, {
+        baseUrl: config.baseUrl
+    });
+    if (command.kind === "apps-list") {
+        return appsListCommand(client, { json: command.json });
+    }
+    if (command.kind === "builds-upload") {
+        return buildsUploadCommand(client, command);
+    }
+    return assertNever(command);
+}
+function assertNever(value) {
+    throw new Error(`Unsupported command payload: ${JSON.stringify(value)}`);
+}
+function isExecutedAsScript() {
+    const executedPath = process.argv[1];
+    if (!executedPath) {
+        return false;
+    }
+    return import.meta.url === pathToFileURL(executedPath).href;
+}
+if (isExecutedAsScript()) {
+    const exitCode = await runCli(process.argv.slice(2), process.env);
+    if (exitCode !== 0) {
+        process.exit(exitCode);
+    }
+}

package/dist/commands/apps-list.d.ts

@@ -0,0 +1,12 @@
+import { type AppStoreConnectClient } from "../api/client.js";
+export interface AppSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly bundleId: string;
+    readonly sku?: string;
+}
+export declare function appsListCommand(client: AppStoreConnectClient, options: {
+    readonly json: boolean;
+}): Promise<number>;
+export declare function listApps(client: AppStoreConnectClient): Promise<readonly AppSummary[]>;
+//# sourceMappingURL=apps-list.d.ts.map

package/dist/commands/apps-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-list.d.ts","sourceRoot":"","sources":["../../src/commands/apps-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAqBnF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,MAAM,CAAC,CA+CjB;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CA4B5F"}

package/dist/commands/apps-list.js

@@ -0,0 +1,63 @@
+import { InfrastructureError } from "../api/client.js";
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+const DEFAULT_LIST_LIMIT = 50;
+export async function appsListCommand(client, options) {
+    const response = await client.request({
+        method: "GET",
+        path: "/v1/apps",
+        query: { limit: DEFAULT_LIST_LIMIT }
+    });
+    const apps = response.data.data.map((item) => {
+        const attributes = item.attributes;
+        if (!item.id || !attributes?.name || !attributes?.bundleId) {
+            throw new InfrastructureError("Malformed app payload received from App Store Connect.");
+        }
+        const summary = {
+            id: item.id,
+            name: attributes.name,
+            bundleId: attributes.bundleId
+        };
+        if (attributes.sku !== undefined) {
+            return { ...summary, sku: attributes.sku };
+        }
+        return summary;
+    });
+    const sorted = [...apps].sort((a, b) => a.name.localeCompare(b.name));
+    if (options.json) {
+        console.log(JSON.stringify(sorted, null, 2));
+        return 0;
+    }
+    if (sorted.length === 0) {
+        console.log("No apps were returned by App Store Connect.");
+        return 0;
+    }
+    console.log("Apps:");
+    for (const app of sorted) {
+        console.log(`- ${app.name} (${app.bundleId}) [${app.id}]`);
+    }
+    return 0;
+}
+export async function listApps(client) {
+    const response = await client.request({
+        method: "GET",
+        path: "/v1/apps",
+        query: { limit: DEFAULT_LIST_LIMIT }
+    });
+    return response.data.data.map((item) => {
+        const attributes = item.attributes;
+        if (!item.id || !attributes?.name || !attributes?.bundleId) {
+            throw new InfrastructureError("Malformed app payload received from App Store Connect.");
+        }
+        const summary = {
+            id: item.id,
+            name: attributes.name,
+            bundleId: attributes.bundleId
+        };
+        if (attributes.sku !== undefined) {
+            return { ...summary, sku: attributes.sku };
+        }
+        return summary;
+    });
+}

package/dist/commands/builds-upload.d.ts

@@ -0,0 +1,45 @@
+import { type AppStoreConnectClient } from "../api/client.js";
+import { type IpaSource, type ProcessRunner } from "../ipa/artifact.js";
+export interface BuildsUploadInput {
+    readonly ipaSource: IpaSource;
+    readonly appId: string;
+    readonly expectedBundleId: string;
+    readonly expectedVersion: string;
+    readonly expectedBuildNumber: string;
+    readonly waitProcessing: boolean;
+    readonly apply: boolean;
+}
+export interface BuildsUploadResult {
+    readonly mode: "dry-run" | "applied";
+    readonly preflightReport: {
+        readonly ipaPath: string;
+        readonly bundleId: string | null;
+        readonly version: string | null;
+        readonly buildNumber: string | null;
+        readonly sizeBytes: number;
+        readonly sha256: string | null;
+        readonly md5: string | null;
+        readonly signingValidated: boolean;
+        readonly errors: readonly string[];
+        readonly warnings: readonly string[];
+    };
+    readonly plannedOperations: readonly string[];
+    readonly buildUploadId: string | null;
+    readonly finalBuildUploadState: string | null;
+}
+export declare function uploadBuild(client: AppStoreConnectClient, input: BuildsUploadInput, options?: {
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly pollIntervalMs?: number;
+    readonly pollTimeoutMs?: number;
+    readonly processRunner?: ProcessRunner;
+}): Promise<BuildsUploadResult>;
+export declare function buildsUploadCommand(client: AppStoreConnectClient, command: {
+    readonly appReference: string;
+    readonly version: string;
+    readonly buildNumber: string;
+    readonly ipaSource: IpaSource;
+    readonly waitProcessing: boolean;
+    readonly apply: boolean;
+    readonly json: boolean;
+}): Promise<number>;
+//# sourceMappingURL=builds-upload.d.ts.map

package/dist/commands/builds-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builds-upload.d.ts","sourceRoot":"","sources":["../../src/commands/builds-upload.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAsB,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAuO5F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C;AAKD,wBAAsB,WAAW,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC,GACA,OAAO,CAAC,kBAAkB,CAAC,CAoG7B;AAiCD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE;IACP,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,GACA,OAAO,CAAC,MAAM,CAAC,CA2BjB"}

package/dist/commands/builds-upload.js

@@ -0,0 +1,262 @@
+import { DomainError, InfrastructureError } from "../api/client.js";
+import { executeUploadOperations, parseUploadOperations } from "../api/types.js";
+import { resolveIpaArtifact } from "../ipa/artifact.js";
+import { verifyIpa } from "../ipa/preflight.js";
+import { listApps } from "./apps-list.js";
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+function mapBuildUpload(response) {
+    const data = response.data;
+    const id = data.id;
+    if (!id) {
+        throw new InfrastructureError("Malformed build upload payload: missing id.");
+    }
+    const stateValue = data.attributes?.state?.state;
+    if (!stateValue) {
+        throw new InfrastructureError("Malformed build upload payload: missing state.");
+    }
+    const stateObj = data.attributes?.state;
+    return {
+        id,
+        state: {
+            state: stateValue,
+            errors: (stateObj?.errors ?? []).map((item) => item.description ?? "Unknown error"),
+            warnings: (stateObj?.warnings ?? []).map((item) => item.description ?? "Unknown warning"),
+            infos: (stateObj?.infos ?? []).map((item) => item.description ?? "Unknown info")
+        }
+    };
+}
+async function createBuildUpload(client, input) {
+    const response = await client.request({
+        method: "POST",
+        path: "/v1/buildUploads",
+        body: {
+            data: {
+                type: "buildUploads",
+                attributes: {
+                    cfBundleShortVersionString: input.versionString,
+                    cfBundleVersion: input.buildNumber,
+                    platform: input.platform
+                },
+                relationships: {
+                    app: {
+                        data: {
+                            type: "apps",
+                            id: input.appId
+                        }
+                    }
+                }
+            }
+        }
+    });
+    return mapBuildUpload(response.data);
+}
+async function createBuildUploadFile(client, input) {
+    const response = await client.request({
+        method: "POST",
+        path: "/v1/buildUploadFiles",
+        body: {
+            data: {
+                type: "buildUploadFiles",
+                attributes: {
+                    assetType: input.assetType,
+                    fileName: input.fileName,
+                    fileSize: input.fileSize,
+                    uti: input.uti
+                },
+                relationships: {
+                    buildUpload: {
+                        data: {
+                            type: "buildUploads",
+                            id: input.buildUploadId
+                        }
+                    }
+                }
+            }
+        }
+    });
+    const id = response.data.data.id;
+    const operationsPayload = response.data.data.attributes?.uploadOperations ?? [];
+    if (!id) {
+        throw new InfrastructureError("Malformed build upload file payload: missing id.");
+    }
+    return {
+        id,
+        uploadOperations: parseUploadOperations(operationsPayload, "build upload file")
+    };
+}
+async function markBuildUploadFileUploaded(client, input) {
+    await client.request({
+        method: "PATCH",
+        path: `/v1/buildUploadFiles/${input.buildUploadFileId}`,
+        body: {
+            data: {
+                type: "buildUploadFiles",
+                id: input.buildUploadFileId,
+                attributes: {
+                    sourceFileChecksums: {
+                        file: {
+                            hash: input.sha256,
+                            algorithm: "SHA_256"
+                        },
+                        composite: {
+                            hash: input.md5,
+                            algorithm: "MD5"
+                        }
+                    },
+                    uploaded: true
+                }
+            }
+        }
+    });
+}
+async function getBuildUpload(client, buildUploadId) {
+    const response = await client.request({
+        method: "GET",
+        path: `/v1/buildUploads/${buildUploadId}`,
+        query: {
+            "fields[buildUploads]": "state"
+        }
+    });
+    return mapBuildUpload(response.data);
+}
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 60 * 1_000;
+export async function uploadBuild(client, input, options) {
+    const sleep = options?.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const pollIntervalMs = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const pollTimeoutMs = options?.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const artifact = await resolveIpaArtifact(input.ipaSource, options?.processRunner);
+    try {
+        const preflightReport = await verifyIpa({
+            ipaPath: artifact.ipaPath,
+            expectedBundleId: input.expectedBundleId,
+            expectedVersion: input.expectedVersion,
+            expectedBuildNumber: input.expectedBuildNumber
+        }, options?.processRunner);
+        if (preflightReport.errors.length > 0) {
+            throw new DomainError(`IPA preflight verification failed: ${preflightReport.errors.join(" | ")}`);
+        }
+        const plannedOperations = [
+            `Create build upload for app ${input.appId}`,
+            `Create build upload file for ${artifact.ipaPath}`,
+            "Upload chunks using App Store Connect upload operations",
+            "Mark build upload file as uploaded with checksums",
+            input.waitProcessing
+                ? "Poll build upload until terminal state"
+                : "Fetch current build upload state once"
+        ];
+        if (!input.apply) {
+            return {
+                mode: "dry-run",
+                preflightReport,
+                plannedOperations,
+                buildUploadId: null,
+                finalBuildUploadState: null
+            };
+        }
+        const buildUpload = await createBuildUpload(client, {
+            appId: input.appId,
+            versionString: input.expectedVersion,
+            buildNumber: input.expectedBuildNumber,
+            platform: "IOS"
+        });
+        const fileName = artifact.ipaPath.split(/[\\/]/).at(-1) ?? "build.ipa";
+        const buildUploadFile = await createBuildUploadFile(client, {
+            buildUploadId: buildUpload.id,
+            fileName,
+            fileSize: preflightReport.sizeBytes,
+            uti: "com.apple.ipa",
+            assetType: "ASSET"
+        });
+        await executeUploadOperations(artifact.ipaPath, buildUploadFile.uploadOperations);
+        const sha256 = preflightReport.sha256;
+        const md5 = preflightReport.md5;
+        if (!sha256 || !md5) {
+            throw new DomainError("Missing checksums in preflight report; cannot mark build upload file as uploaded.");
+        }
+        await markBuildUploadFileUploaded(client, {
+            buildUploadFileId: buildUploadFile.id,
+            sha256,
+            md5
+        });
+        const finalState = input.waitProcessing
+            ? await pollBuildUploadState(client, buildUpload.id, sleep, pollIntervalMs, pollTimeoutMs)
+            : (await getBuildUpload(client, buildUpload.id)).state.state;
+        if (finalState === "FAILED") {
+            throw new DomainError("Build upload failed in App Store Connect.");
+        }
+        return {
+            mode: "applied",
+            preflightReport,
+            plannedOperations,
+            buildUploadId: buildUpload.id,
+            finalBuildUploadState: finalState
+        };
+    }
+    finally {
+        if (artifact.dispose) {
+            await artifact.dispose();
+        }
+    }
+}
+async function pollBuildUploadState(client, buildUploadId, sleep, pollIntervalMs, pollTimeoutMs) {
+    const startedAt = Date.now();
+    while (true) {
+        const buildUpload = await getBuildUpload(client, buildUploadId);
+        const state = buildUpload.state.state;
+        if (state === "COMPLETE" || state === "FAILED") {
+            return state;
+        }
+        if (Date.now() - startedAt > pollTimeoutMs) {
+            throw new DomainError(`Timed out while waiting for build upload processing (${buildUploadId}).`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI command
+// ---------------------------------------------------------------------------
+export async function buildsUploadCommand(client, command) {
+    const apps = await listApps(client);
+    const app = apps.find((a) => a.id === command.appReference || a.bundleId === command.appReference);
+    if (!app) {
+        throw new Error(`Could not resolve app reference "${command.appReference}".`);
+    }
+    const result = await uploadBuild(client, {
+        ipaSource: command.ipaSource,
+        appId: app.id,
+        expectedBundleId: app.bundleId,
+        expectedVersion: command.version,
+        expectedBuildNumber: command.buildNumber,
+        waitProcessing: command.waitProcessing,
+        apply: command.apply
+    });
+    if (command.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printBuildUploadResult(result, app);
+    }
+    return 0;
+}
+function printBuildUploadResult(result, app) {
+    console.log(`Mode: ${result.mode}`);
+    console.log(`App: ${app.name} (${app.bundleId}) [${app.id}]`);
+    console.log(`IPA: ${result.preflightReport.ipaPath}`);
+    console.log(`SHA-256: ${result.preflightReport.sha256 ?? "unavailable"}`);
+    console.log(`Signing validated: ${result.preflightReport.signingValidated ? "yes" : "no"}`);
+    console.log("Planned operations:");
+    result.plannedOperations.forEach((operation) => {
+        console.log(`- ${operation}`);
+    });
+    if (result.mode === "dry-run") {
+        console.log("Dry-run completed. No App Store Connect mutation requests were sent.");
+    }
+    else {
+        console.log(`Build upload id: ${result.buildUploadId}`);
+        console.log(`Final state: ${result.finalBuildUploadState}`);
+    }
+}