@run-cloud/sdk 0.27.0 → 0.29.0

package/README.md

@@ -67,6 +67,16 @@ 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
@@ -75,6 +85,8 @@ ID to members of the owning organization. Source packaging honors the root
 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
 
@@ -557,8 +569,10 @@ ends.
 QuickTime blobs and imports them into Photos. The video is stored as a
 user-owned run.cloud asset and remains available through `cloud.assets`.
 
-`cloud.ios.uploadMicrophoneAudio(sessionId, audioBlob, { filename, bundleId })`
-accepts AAC, M4A, MP3, MP4 audio, and WAV. It relaunches the foreground app
-(or `bundleId`) with microphone permission and loops the decoded audio through
-the app's `AVAudioEngine` input tap. The uploaded source remains in
-`cloud.assets`.
+`cloud.ios.uploadCameraVideo(...)` and `cloud.android.uploadCameraVideo(...)`
+accept MP4 and QuickTime blobs and loop them through the target app camera.
+`cloud.ios.uploadMicrophoneAudio(...)` and
+`cloud.android.uploadMicrophoneAudio(...)` accept AAC, M4A, MP3, MP4 audio,
+and WAV and deliver decoded samples through the target app microphone. Pass
+`bundleId` to name the target app. Both results contain the retained uploaded
+asset; delete it through `cloud.assets` when it is no longer needed.

package/dist/index.d.ts

@@ -70,7 +70,7 @@ export type SimulatorInteraction = {
     enabled: boolean;
 };
 export type SimulatorInteractionAction = SimulatorInteraction["action"];
-export type SimulatorOperation = SimulatorInteractionAction | "screenshot" | "accessibility" | "install" | "activity" | "metro-tunnel" | "open-url";
+export type SimulatorOperation = SimulatorInteractionAction | "screenshot" | "accessibility" | "install" | "activity" | "camera-video" | "microphone-audio" | "metro-tunnel" | "open-url";
 export declare const SIMULATOR_SESSION_ERROR_CODES: readonly ["simulator_capacity_unavailable"];
 export type SimulatorSessionErrorCode = (typeof SIMULATOR_SESSION_ERROR_CODES)[number];
 export declare const SIMULATOR_OPEN_URL_ERROR_CODES: readonly ["invalid_url", "active_session_not_found", "open_url_scope_required", "simulator_session_ended", "ios_url_handler_not_found", "android_url_handler_not_found", "simulator_unavailable", "open_url_timeout", "ios_open_url_failed", "android_open_url_failed", "open_url_transport_error", "open_url_invalid_response", "open_url_failed"];
@@ -282,6 +282,12 @@ export interface AggregateSimulatorRecordingStartOptions extends SimulatorRecord
 export interface AggregateSimulatorRecordingRequestOptions extends SimulatorRecordingRequestOptions {
     platform?: SimulatorPlatform;
 }
+export interface AggregateSimulatorCameraVideoOptions extends SimulatorCameraVideoOptions {
+    platform?: SimulatorPlatform;
+}
+export interface AggregateSimulatorMicrophoneAudioOptions extends SimulatorMicrophoneAudioOptions {
+    platform?: SimulatorPlatform;
+}
 export declare const DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS = 15000;
 export declare const DEFAULT_SIMULATOR_ACCESSIBILITY_TIMEOUT_MS = 20000;
 export declare function validateSimulatorInteraction(interaction: SimulatorInteraction, timeoutMs?: number): void;
@@ -367,6 +373,7 @@ export interface SandboxHistory {
 }
 export interface Asset {
     id: string;
+    orgId?: string | null;
     name: string;
     filename: string;
     contentType: string;
@@ -386,11 +393,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. */
@@ -411,13 +428,31 @@ export interface VideoUploadResult {
     byteSize: number;
     asset: Asset;
 }
+export interface CameraVideoResult {
+    ok: true;
+    platform: SimulatorPlatform;
+    sessionId: string;
+    bundleId: string | null;
+    filename: string;
+    contentType: "video/mp4" | "video/quicktime";
+    byteSize: number;
+    source: "video";
+    pid: number | null;
+    asset: Asset;
+}
 export interface MicrophoneAudioResult {
     ok: true;
+    platform: SimulatorPlatform;
+    sessionId: string;
     bundleId: string;
     filename: string;
     contentType: string;
     byteSize: number;
     pid: number | null;
+    sampleRate?: number;
+    channels?: number;
+    sampleCount?: number;
+    durationMs?: number;
     asset: Asset;
 }
 export type XcodeSdk = "iphonesimulator" | "iphoneos" | "watchsimulator" | "watchos";
@@ -496,13 +531,20 @@ export interface XcodeBuildOptions extends XcodeProjectOptions {
     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;
 }
@@ -531,6 +573,11 @@ export interface XcodeBuild {
         byteSize: number;
     };
     artifact: XcodeBuildArtifact;
+    reuse: {
+        mode: "full" | "rebundle";
+        basisBuildId: string | null;
+        nativeFingerprint: string | null;
+    };
     logs: {
         available: boolean;
         url: string;
@@ -555,6 +602,22 @@ 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;
@@ -563,6 +626,7 @@ export interface XcodeBuildWaitOptions {
     signal?: AbortSignal;
 }
 export interface CreateSessionOptions {
+    orgId?: string;
     /** Retry-safe create: reuse this value to receive the original simulator session. */
     idempotencyKey?: string;
     model?: string;
@@ -585,6 +649,7 @@ export interface SimulatorStream {
 }
 export interface SimulatorSession {
     id: string;
+    orgId: string | null;
     platform: SimulatorPlatform;
     status: "active" | "released" | "failed" | string;
     model?: string | null;
@@ -608,6 +673,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;
@@ -622,6 +746,16 @@ export interface SimulatorInstallOptions {
     filename?: string;
     name?: string;
 }
+export interface SimulatorCameraVideoOptions {
+    filename?: string;
+    name?: string;
+    bundleId?: string;
+}
+export interface SimulatorMicrophoneAudioOptions {
+    filename?: string;
+    name?: string;
+    bundleId?: string;
+}
 export interface SimulatorInstallResult {
     ok: true;
     platform: SimulatorPlatform;
@@ -1089,6 +1223,8 @@ export declare class Client {
     readonly images: ImageClient;
     readonly remotion: RemotionClient;
     readonly xcode: XcodeBuildsClient;
+    readonly capabilities: CapabilitiesClient;
+    readonly mobile: MobileClient;
     private readonly apiKey;
     private readonly apiUrl;
     private readonly fetchImpl;
@@ -1141,12 +1277,21 @@ export declare class XcodeBuildsClient {
     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[]>;
-    logs(id: string, offset?: number): Promise<XcodeBuildLogChunk>;
+    /** 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>;
@@ -1164,11 +1309,16 @@ 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>;
     installAsset(id: string, assetId: string): Promise<SimulatorInstallResult>;
     install(id: string, application: Blob, options?: SimulatorInstallOptions): Promise<SimulatorInstallResult>;
+    /** Upload a deterministic video and present it to the app as live camera input. */
+    uploadCameraVideo(id: string, video: Blob, options?: SimulatorCameraVideoOptions): Promise<CameraVideoResult>;
+    /** Upload audio and deliver its decoded samples to the app microphone. */
+    uploadMicrophoneAudio(id: string, audio: Blob, options?: SimulatorMicrophoneAudioOptions): Promise<MicrophoneAudioResult>;
     keepAlive(id: string): Promise<SimulatorActivityResult>;
     openMetroTunnel(id: string, options: SimulatorMetroTunnelOptions): Promise<SimulatorMetroTunnel>;
     openUrl(id: string, url: string): Promise<SimulatorOpenUrlResult>;
@@ -1211,11 +1361,6 @@ export declare class IosSimulatorClient extends SimulatorClient {
         filename?: string;
         name?: string;
     }): Promise<VideoUploadResult>;
-    uploadMicrophoneAudio(id: string, audio: Blob, options?: {
-        filename?: string;
-        name?: string;
-        bundleId?: string;
-    }): Promise<MicrophoneAudioResult>;
 }
 export declare class SimulatorsClient {
     private readonly client;
@@ -1226,6 +1371,7 @@ export declare class SimulatorsClient {
     list(options?: {
         platform?: SimulatorPlatform;
         all?: boolean;
+        orgId?: string;
     }): Promise<SimulatorSession[]>;
     get(id: string, options?: {
         platform?: SimulatorPlatform;
@@ -1242,6 +1388,8 @@ export declare class SimulatorsClient {
     install(id: string, application: Blob, options?: SimulatorInstallOptions & {
         platform?: SimulatorPlatform;
     }): Promise<SimulatorInstallResult>;
+    uploadCameraVideo(id: string, video: Blob, options?: AggregateSimulatorCameraVideoOptions): Promise<CameraVideoResult>;
+    uploadMicrophoneAudio(id: string, audio: Blob, options?: AggregateSimulatorMicrophoneAudioOptions): Promise<MicrophoneAudioResult>;
     keepAlive(id: string, options?: {
         platform?: SimulatorPlatform;
     }): Promise<SimulatorActivityResult>;
@@ -1585,7 +1733,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. */
@@ -1602,3 +1752,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>;
+}