@run-cloud/sdk 0.26.0 → 0.28.0

package/README.md

@@ -51,6 +51,43 @@ await writeFile(
 await cloud.android.delete(android.id);
 ```
 
+## Xcode builds
+
+```ts
+const submitted = await cloud.xcode.build(process.cwd(), {
+  project: "MyApp.xcodeproj",
+  scheme: "MyApp",
+  sdk: "iphonesimulator",
+  idempotencyKey: `xcode-${process.env.GITHUB_SHA ?? "local"}`,
+});
+const completed = await cloud.xcode.wait(submitted.id, {
+  onLog: (text) => process.stdout.write(text),
+});
+if (completed.status !== "succeeded") {
+  throw new Error(`${completed.failure?.reason}\n${completed.failure?.action}`);
+}
+await writeFile("MyApp.tar.gz", await cloud.xcode.downloadArtifact(completed.id));
+
+const rebuilt = await cloud.xcode.rebundle(process.cwd(), completed.id, {
+  idempotencyKey: `rebundle-${completed.id}-${process.env.GITHUB_SHA ?? "local"}`,
+});
+const ready = await cloud.xcode.wait(rebuilt.id);
+const launch = await cloud.mobile.launch(
+  { buildId: ready.id },
+  { idempotencyKey: `launch-${ready.id}`, orgId: ready.orgId },
+);
+console.log(launch.id, launch.sessionId, launch.status);
+```
+
+Build records, sanitized logs, failure reasons, and artifacts stay available by
+ID to members of the owning organization. Source packaging honors the root
+`.gitignore`, drops common Xcode and dependency output, and supports explicit
+include, ignore, and additional-file rules. Full options and intentional
+differences are documented at
+[docs.run.cloud/ios/build-with-xcode](https://docs.run.cloud/ios/build-with-xcode).
+Use `cloud.xcode.events` for replayable lifecycle delivery and
+`cloud.capabilities.create` for short-lived access to selected resources.
+
 ## Retry-safe simulator creates
 
 Simulator creates are retry-safe when `idempotencyKey` is set. Reuse the same

package/dist/index.d.ts

@@ -367,6 +367,7 @@ export interface SandboxHistory {
 }
 export interface Asset {
     id: string;
+    orgId?: string | null;
     name: string;
     filename: string;
     contentType: string;
@@ -386,11 +387,21 @@ export interface Asset {
         retries?: number;
         throughputBps?: number | null;
     };
+    origin?: {
+        kind: "upload";
+    } | {
+        kind: "xcode-build";
+        buildId: string;
+    };
+    parentAssetId?: string | null;
+    immutable?: boolean;
+    metadata?: Record<string, unknown>;
     createdAt: string;
     /** Authenticated API path; GET follows a short-lived signed storage redirect. */
     downloadUrl: string;
 }
 export interface AssetUploadOptions {
+    orgId?: string;
     name?: string;
     filename?: string;
     /** Stable archive/batch identifier shared by every part in one logical upload. */
@@ -420,7 +431,178 @@ export interface MicrophoneAudioResult {
     pid: number | null;
     asset: Asset;
 }
+export type XcodeSdk = "iphonesimulator" | "iphoneos" | "watchsimulator" | "watchos";
+export type XcodeConfiguration = "Debug" | "Release";
+export type XcodeCloudSigningMethod = "app-store-connect" | "release-testing" | "debugging";
+export type XcodeBuildStatus = "uploading" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
+export interface XcodeProjectOptions {
+    workspace?: string;
+    project?: string;
+    scheme?: string;
+    sdk?: XcodeSdk;
+    configuration?: XcodeConfiguration;
+}
+export interface XcodeGenOptions {
+    spec?: string;
+    project?: string;
+    projectRoot?: string;
+}
+export interface XcodeManualSigningOptions {
+    certificateP12Base64: string;
+    certificatePassword: string;
+    provisioningProfilesBase64?: string[];
+    /** Convenience alias for one provisioning profile. */
+    provisioningProfileBase64?: string;
+}
+export interface XcodeCloudSigningOptions {
+    method: XcodeCloudSigningMethod;
+    teamId: string;
+    apiKeyId: string;
+    apiIssuerId: string;
+    apiPrivateKeyBase64: string;
+}
+export interface XcodeAppStoreOptions {
+    enabled?: boolean;
+    apiKeyId: string;
+    apiIssuerId?: string;
+    apiPrivateKeyBase64: string;
+    waitTimeoutSeconds?: number;
+    autoIncrementBuildNumber?: boolean;
+}
+export interface XcodeReactNativeOptions {
+    expoAppDir?: string;
+    devServerUrl?: string;
+    /** Legacy spelling accepted for compatibility. */
+    devServerURL?: string;
+}
+export type XcodeUploadOptions = {
+    assetName: string;
+    signedUploadUrl?: never;
+} | {
+    signedUploadUrl: string;
+    assetName?: never;
+};
+export interface XcodeAdditionalFile {
+    localPath: string;
+    remotePath: string;
+}
+export type XcodePathMatcher = string | RegExp | ((relativePath: string) => boolean);
+export interface XcodeSourceOptions {
+    ignore?: XcodePathMatcher | XcodePathMatcher[];
+    include?: XcodePathMatcher | XcodePathMatcher[];
+    additionalFiles?: XcodeAdditionalFile[];
+}
+export interface XcodeBuildOptions extends XcodeProjectOptions {
+    orgId?: string;
+    xcodegen?: XcodeGenOptions;
+    reactNative?: XcodeReactNativeOptions;
+    buildSettings?: Record<string, string>;
+    signing?: XcodeManualSigningOptions;
+    cloudSigning?: XcodeCloudSigningOptions;
+    appStore?: XcodeAppStoreOptions;
+    /** Legacy spelling accepted for compatibility. */
+    appstore?: XcodeAppStoreOptions;
+    upload?: XcodeUploadOptions;
+    gitInit?: boolean;
+    timeoutSeconds?: number;
+    source?: XcodeSourceOptions;
+    idempotencyKey?: string;
+    /** Native shell whose compatible JavaScript bundle should be replaced. */
+    reuse?: {
+        basisBuildId: string;
+    };
+}
+export type XcodeRebundleOptions = Omit<XcodeBuildOptions, "workspace" | "project" | "scheme" | "sdk" | "configuration" | "xcodegen" | "signing" | "cloudSigning" | "appStore" | "appstore" | "reuse">;
+export interface XcodeBuildArtifact {
+    kind: "simulator-app" | "device-app" | "signed-ipa" | "watch-app";
+    filename: string;
+    contentType: string;
+    byteSize: number | null;
+    available: boolean;
+    /** Reusable run.cloud Asset identity for this immutable output. */
+    assetId: string | null;
+    /** Authenticated endpoint that redirects to a short-lived object URL. */
+    downloadUrl: string | null;
+}
+export interface XcodeBuildFailure {
+    reason: string;
+    category: string;
+    stage: string | null;
+    action: string;
+}
+export interface XcodeBuild {
+    id: string;
+    orgId: string;
+    createdBy: string;
+    idempotencyKey: string;
+    status: XcodeBuildStatus;
+    result: {
+        status: "SUCCEEDED" | "FAILED" | "CANCELLED";
+        exitCode: number | null;
+    } | null;
+    options: Record<string, unknown> & {
+        sdk: XcodeSdk;
+    };
+    source: {
+        kind: "source-archive";
+        sha256: string;
+        byteSize: number;
+    };
+    artifact: XcodeBuildArtifact;
+    reuse: {
+        mode: "full" | "rebundle";
+        basisBuildId: string | null;
+        nativeFingerprint: string | null;
+    };
+    logs: {
+        available: boolean;
+        url: string;
+        retained: boolean;
+    };
+    runner: {
+        provider: "jenkins";
+        job: string;
+        queueId: string | null;
+        runId: string | null;
+    };
+    failure: XcodeBuildFailure | null;
+    timings: {
+        createdAt: string;
+        queuedAt: string | null;
+        startedAt: string | null;
+        completedAt: string | null;
+        updatedAt: string;
+    };
+}
+export interface XcodeBuildLogChunk {
+    text: string;
+    nextOffset: number;
+    complete: boolean;
+    source?: "live" | "retained";
+}
+export interface XcodeBuildEvent {
+    sequence: number;
+    id: string;
+    orgId: string;
+    buildId: string;
+    type: string;
+    status: XcodeBuildStatus;
+    stage: string | null;
+    data: Record<string, unknown>;
+    createdAt: string;
+}
+export interface XcodeBuildEventPage {
+    items: XcodeBuildEvent[];
+    nextCursor: number;
+}
+export interface XcodeBuildWaitOptions {
+    onLog?: (text: string) => void;
+    pollIntervalMs?: number;
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+}
 export interface CreateSessionOptions {
+    orgId?: string;
     /** Retry-safe create: reuse this value to receive the original simulator session. */
     idempotencyKey?: string;
     model?: string;
@@ -443,6 +625,7 @@ export interface SimulatorStream {
 }
 export interface SimulatorSession {
     id: string;
+    orgId: string | null;
     platform: SimulatorPlatform;
     status: "active" | "released" | "failed" | string;
     model?: string | null;
@@ -466,6 +649,65 @@ export interface SimulatorSession {
     queueAttempts?: number;
     metering?: Record<string, unknown>;
 }
+export type RunCloudCapabilityScope = "asset.read" | "mobile.launch" | "xcode.build.create" | "xcode.build.read";
+export interface RunCloudCapabilityResources {
+    assetIds?: string[];
+    buildIds?: string[];
+    idempotencyKeys?: string[];
+}
+export interface RunCloudCapability {
+    id: string;
+    orgId: string;
+    createdBy: string;
+    name: string | null;
+    scopes: RunCloudCapabilityScope[];
+    resources: RunCloudCapabilityResources;
+    expiresAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface CreateCapabilityOptions {
+    scopes: RunCloudCapabilityScope[];
+    resources: RunCloudCapabilityResources;
+    orgId?: string;
+    name?: string;
+    expiresInSeconds?: number;
+}
+export interface MobileLaunch {
+    id: string;
+    orgId: string;
+    idempotencyKey: string;
+    status: "provisioning" | "succeeded" | "failed";
+    platform: SimulatorPlatform;
+    source: {
+        assetId: string;
+        buildId: string | null;
+    };
+    sessionId: string;
+    session: SimulatorSession | null;
+    failure: {
+        reason: string;
+        code: string;
+        action: string;
+    } | null;
+    createdAt: string;
+    completedAt: string | null;
+    updatedAt: string;
+}
+export type MobileLaunchSource = {
+    assetId: string;
+    buildId?: never;
+} | {
+    buildId: string;
+    assetId?: never;
+};
+export interface MobileLaunchOptions {
+    idempotencyKey: string;
+    orgId?: string;
+    platform?: SimulatorPlatform;
+    session?: Omit<CreateSessionOptions, "orgId" | "idempotencyKey" | "installAssets">;
+}
 /** Confirmation that a URL was dispatched to the authenticated simulator lease. */
 export interface SimulatorOpenUrlResult {
     ok: true;
@@ -929,6 +1171,11 @@ export type SimulatorCapacityError = RunCloudError & {
 };
 /** Narrow a failed simulator create to the public, retry-safe capacity response. */
 export declare function isSimulatorCapacityError(error: unknown): error is SimulatorCapacityError;
+/** Create the source archive accepted by the run.cloud Xcode build endpoint. */
+export declare function packXcodeSource(sourcePath: string, options?: XcodeSourceOptions): Promise<{
+    archive: Uint8Array;
+    filename: string;
+}>;
 export declare class Client {
     readonly ios: IosSimulatorClient;
     readonly android: SimulatorClient;
@@ -941,6 +1188,9 @@ export declare class Client {
     readonly ci: CiClient;
     readonly images: ImageClient;
     readonly remotion: RemotionClient;
+    readonly xcode: XcodeBuildsClient;
+    readonly capabilities: CapabilitiesClient;
+    readonly mobile: MobileClient;
     private readonly apiKey;
     private readonly apiUrl;
     private readonly fetchImpl;
@@ -973,7 +1223,7 @@ export declare class Client {
      */
     setName(name: string): Promise<Account>;
     request<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>, abortOptions?: RequestAbortOptions): Promise<T>;
-    uploadForm<T>(path: string, form: FormData): Promise<T>;
+    uploadForm<T>(path: string, form: FormData, headers?: Record<string, string>): Promise<T>;
     requestBytes(path: string, abortOptions?: RequestAbortOptions): Promise<Uint8Array>;
     requestTextStream(path: string, signal?: AbortSignal): AsyncGenerator<string>;
     /**
@@ -988,6 +1238,31 @@ export declare class Client {
     putSigned(url: string, body: Blob, headers: Record<string, string>): Promise<void>;
     execStream(path: string, request: Record<string, unknown>, callbacks?: Pick<ExecOptions, "onStdout" | "onStderr" | "signal">): Promise<ExecResult>;
 }
+export declare class XcodeBuildsClient {
+    private readonly client;
+    constructor(client: Client);
+    /** Package a local source tree and submit one idempotent remote Xcode build. */
+    build(sourcePath?: string, options?: XcodeBuildOptions): Promise<XcodeBuild>;
+    /** Reuse a compatible simulator native shell and replace only its embedded JavaScript bundle. */
+    rebundle(sourcePath: string, basisBuildId: string, options?: XcodeRebundleOptions): Promise<XcodeBuild>;
+    get(id: string): Promise<XcodeBuild>;
+    list(options?: {
+        orgId?: string;
+        limit?: number;
+    }): Promise<XcodeBuild[]>;
+    /** Read an ordered, replayable event page. Persist nextCursor after processing the page. */
+    events(options?: {
+        orgId?: string;
+        after?: number;
+        buildId?: string;
+        limit?: number;
+    }): Promise<XcodeBuildEventPage>;
+    logs(id: string, offset?: number, source?: XcodeBuildLogChunk["source"]): Promise<XcodeBuildLogChunk>;
+    /** Poll state and emit sanitized log chunks until the build is terminal. */
+    wait(id: string, options?: XcodeBuildWaitOptions): Promise<XcodeBuild>;
+    cancel(id: string): Promise<XcodeBuild>;
+    downloadArtifact(id: string): Promise<Uint8Array>;
+}
 export declare class SimulatorClient {
     protected readonly client: Client;
     readonly platform: SimulatorPlatform;
@@ -1000,6 +1275,7 @@ export declare class SimulatorClient {
     setTags(id: string, tags: Record<string, string | null>): Promise<SimulatorSession>;
     list(options?: {
         all?: boolean;
+        orgId?: string;
     }): Promise<SimulatorSession[]>;
     get(id: string): Promise<SimulatorSession>;
     delete(id: string): Promise<SimulatorSession>;
@@ -1062,6 +1338,7 @@ export declare class SimulatorsClient {
     list(options?: {
         platform?: SimulatorPlatform;
         all?: boolean;
+        orgId?: string;
     }): Promise<SimulatorSession[]>;
     get(id: string, options?: {
         platform?: SimulatorPlatform;
@@ -1421,7 +1698,9 @@ export declare class AssetsClient {
     private readonly waitingUploads;
     private readonly defaultUploadRunId;
     constructor(client: Client);
-    list(): Promise<Asset[]>;
+    list(options?: {
+        orgId?: string;
+    }): Promise<Asset[]>;
     /** Upload through the buffered multipart endpoint instead of signed storage URLs. */
     uploadDirect(file: Blob, options?: Pick<AssetUploadOptions, "name" | "filename">): Promise<Asset>;
     /** Download an owned asset, following the API's short-lived signed redirect. */
@@ -1438,3 +1717,24 @@ export declare class AssetsClient {
         deleted: boolean;
     }>;
 }
+export declare class CapabilitiesClient {
+    private readonly client;
+    constructor(client: Client);
+    /** Mint a short-lived bearer token. The token is returned only by this call. */
+    create(options: CreateCapabilityOptions): Promise<{
+        capability: RunCloudCapability;
+        token: string;
+    }>;
+    list(options?: {
+        orgId?: string;
+        active?: boolean;
+    }): Promise<RunCloudCapability[]>;
+    revoke(id: string): Promise<RunCloudCapability>;
+}
+export declare class MobileClient {
+    private readonly client;
+    constructor(client: Client);
+    /** Idempotently create a mobile session and install one existing Asset or Xcode build output. */
+    launch(source: MobileLaunchSource, options: MobileLaunchOptions): Promise<MobileLaunch>;
+    getLaunch(id: string): Promise<MobileLaunch>;
+}