@builder.io/ai-utils 0.17.2 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/projects.d.ts CHANGED
@@ -1,4 +1,13 @@
1
- import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition } from "./codegen";
1
+ import type {
2
+ FileOverride,
3
+ EnvironmentVariable,
4
+ LaunchServerState,
5
+ LaunchServerStatus,
6
+ BranchBackup,
7
+ CommitMode,
8
+ CustomInstruction,
9
+ CustomAgentDefinition,
10
+ } from "./codegen";
2
11
  /**
3
12
  * Temporary type for date fields during migration.
4
13
  * Handles both old (string) and new (number) formats.
@@ -11,162 +20,291 @@ export type InMigrationDate = string | number;
11
20
  */
12
21
  export type InMigrationDateNullable = InMigrationDate | null | undefined;
13
22
  export interface ConfigStatus {
14
- isReady: boolean;
15
- lastUpdated: string;
16
- [key: string]: unknown;
23
+ isReady: boolean;
24
+ lastUpdated: string;
25
+ [key: string]: unknown;
17
26
  }
18
27
  interface BaseMessage {
19
- timestamp: string;
28
+ timestamp: string;
20
29
  }
21
30
  export interface InitializingMessage extends BaseMessage {
22
- state: "initializing";
23
- message: string;
31
+ state: "initializing";
32
+ message: string;
24
33
  }
25
34
  export interface FetchingGithubTokenMessage extends BaseMessage {
26
- state: "fetchingGithubToken";
27
- message: string;
35
+ state: "fetchingGithubToken";
36
+ message: string;
28
37
  }
29
38
  export interface FetchingFusionKeyMessage extends BaseMessage {
30
- state: "fetchingFusionKey";
31
- message: string;
39
+ state: "fetchingFusionKey";
40
+ message: string;
32
41
  }
33
42
  export interface CheckingAppMessage extends BaseMessage {
34
- state: "checkingApp";
35
- message: string;
43
+ state: "checkingApp";
44
+ message: string;
36
45
  }
37
46
  export interface CleaningUpAppMessage extends BaseMessage {
38
- state: "cleaningUpApp";
39
- message: string;
47
+ state: "cleaningUpApp";
48
+ message: string;
40
49
  }
41
50
  export interface CreatingAppMessage extends BaseMessage {
42
- state: "creatingApp";
43
- message: string;
51
+ state: "creatingApp";
52
+ message: string;
44
53
  }
45
54
  export interface CheckingIPMessage extends BaseMessage {
46
- state: "checkingIP";
47
- message: string;
55
+ state: "checkingIP";
56
+ message: string;
48
57
  }
49
58
  export interface AllocatingIPMessage extends BaseMessage {
50
- state: "allocatingIP";
51
- message: string;
59
+ state: "allocatingIP";
60
+ message: string;
52
61
  }
53
62
  export interface CheckingMachineMessage extends BaseMessage {
54
- state: "checkingMachine";
55
- message: string;
63
+ state: "checkingMachine";
64
+ message: string;
56
65
  }
57
66
  export interface CheckingVolumeMessage extends BaseMessage {
58
- state: "checkingVolume";
59
- message: string;
67
+ state: "checkingVolume";
68
+ message: string;
60
69
  }
61
70
  export interface ForkingVolumeMessage extends BaseMessage {
62
- state: "forkingVolume";
63
- message: string;
71
+ state: "forkingVolume";
72
+ message: string;
64
73
  }
65
74
  export interface RetryingWithNewRegionMessage extends BaseMessage {
66
- state: "retryingWithNewRegion";
67
- message: string;
75
+ state: "retryingWithNewRegion";
76
+ message: string;
68
77
  }
69
78
  export interface WaitingBeforePollingMessage extends BaseMessage {
70
- state: "waitingBeforePolling";
71
- message: string;
79
+ state: "waitingBeforePolling";
80
+ message: string;
72
81
  }
73
82
  export interface PollingMachineStatusMessage extends BaseMessage {
74
- state: "pollingMachineStatus";
75
- message: string;
83
+ state: "pollingMachineStatus";
84
+ message: string;
76
85
  }
77
86
  export interface WarningStateMessage extends BaseMessage {
78
- state: "warning";
79
- message: string;
80
- errors?: string[];
87
+ state: "warning";
88
+ message: string;
89
+ errors?: string[];
81
90
  }
82
91
  export interface PingMessage extends BaseMessage {
83
- type: "ping";
92
+ type: "ping";
84
93
  }
85
94
  export interface PlainMessage extends BaseMessage {
86
- message: string;
95
+ message: string;
87
96
  }
88
97
  export interface DebugMessage extends BaseMessage {
89
- type: "debug";
90
- message: string;
91
- lockInfo?: any;
92
- error?: string;
98
+ type: "debug";
99
+ message: string;
100
+ lockInfo?: any;
101
+ error?: string;
93
102
  }
94
103
  export interface ErrorMessage extends BaseMessage {
95
- type: "error";
96
- error: string;
97
- details?: any;
98
- message?: string;
99
- code?: string;
104
+ type: "error";
105
+ error: string;
106
+ details?: any;
107
+ message?: string;
108
+ code?: string;
100
109
  }
101
110
  export interface InfoMessage extends BaseMessage {
102
- type: "info";
103
- message: string;
111
+ type: "info";
112
+ message: string;
104
113
  }
105
114
  export interface WarningMessage extends BaseMessage {
106
- type: "warning";
107
- message: string;
108
- errors?: string[];
115
+ type: "warning";
116
+ message: string;
117
+ errors?: string[];
109
118
  }
110
119
  export interface MachineStatusMessage extends BaseMessage {
111
- type: "machineStatus";
112
- status: "unknown" | "created" | "starting" | "started" | "stopping" | "stopped" | "suspending" | "suspended" | "replacing" | "destroying" | "destroyed" | "not-found" | "running" | "failed";
120
+ type: "machineStatus";
121
+ status:
122
+ | "unknown"
123
+ | "created"
124
+ | "starting"
125
+ | "started"
126
+ | "stopping"
127
+ | "stopped"
128
+ | "suspending"
129
+ | "suspended"
130
+ | "replacing"
131
+ | "destroying"
132
+ | "destroyed"
133
+ | "not-found"
134
+ | "running"
135
+ | "failed";
113
136
  }
114
137
  export interface LogsMessage extends BaseMessage {
115
- type: "logs";
116
- logs: string[];
138
+ type: "logs";
139
+ logs: string[];
117
140
  }
118
141
  export interface ConfigStatusMessage extends BaseMessage {
119
- type: "configStatus";
120
- configStatus: ConfigStatus;
142
+ type: "configStatus";
143
+ configStatus: ConfigStatus;
121
144
  }
122
145
  export interface AppCreatedMessage extends BaseMessage {
123
- state: "appCreated";
124
- message: string;
125
- appName: string;
146
+ state: "appCreated";
147
+ message: string;
148
+ appName: string;
126
149
  }
127
150
  export interface MachineCreatedMessage extends BaseMessage {
128
- state: "machineCreated";
129
- message: string;
130
- machineId: string;
151
+ state: "machineCreated";
152
+ message: string;
153
+ machineId: string;
131
154
  }
132
155
  export interface IpAllocatedMessage extends BaseMessage {
133
- state: "ipAllocated";
134
- message: string;
156
+ state: "ipAllocated";
157
+ message: string;
135
158
  }
136
159
  export interface VolumeForkedMessage extends BaseMessage {
137
- state: "volumeForked";
138
- message: string;
139
- volumeId: string;
160
+ state: "volumeForked";
161
+ message: string;
162
+ volumeId: string;
140
163
  }
141
164
  export interface ReadyMessage extends BaseMessage {
142
- state: "ready";
143
- message: string;
144
- url: string;
145
- status?: LaunchServerStatus;
146
- }
147
- export type MachineState = "unknown" | "created" | "starting" | "started" | "stopping" | "stopped" | "suspending" | "suspended" | "replacing" | "destroying" | "destroyed" | "not-found" | "running" | "failed";
148
- export type FlyVolumeState = "unknown" | "creating" | "created" | "extending" | "restoring" | "enabling_remote_export" | "hydrating" | "recovering" | "scheduling_destroy" | "pending_destroy" | "failed";
149
- export type GitAuthErrorCode = "git-auth-failed" | "git-auth-failed-root-repo" | "git-auth-failed-folder-added-by" | "git-auth-failed-folder-created-by" | "git-auth-failed-repo-not-found" | "git-auth-failed-repo-renamed" | "git-auth-failed-folder-server-token" | "git-auth-failed-root-repo-server-token" | "git-auth-failed-ghes-unreachable";
150
- export type EnsureContainerErrorCode = "FAILED_TO_START_MACHINE_ERROR" | "FLY_APP_CHECK_ERROR" | "FLY_CAPACITY_ERROR" | "FLY_PERMISSIONS_TOKEN_ERROR" | "FLY_VOLUME_CREATE_ERROR" | "FLY_VOLUME_FORK_ERROR" | "FLY_VOLUME_DELETE_RECENTLY_FORKED_ERROR" | "FLY_MACHINE_CREATE_ERROR" | "FLY_VOLUME_CHECK_ERROR" | "FLY_NON_MOUNTABLE_VOLUME_ERROR" | "FLY_DEPRECATED_REGION_ERROR" | "FLY_VOLUME_NOT_FOUND" | "FLY_MACHINE_LIMIT_ERROR" | "KUBE_CAPACITY_ERROR" | "KUBE_PERMISSIONS_ERROR" | "KUBE_POD_LIMIT_ERROR" | "KUBE_RESOURCE_QUOTA_ERROR" | "KUBE_NAMESPACE_CHECK_ERROR" | "KUBE_PVC_CREATE_ERROR" | "KUBE_PVC_CHECK_ERROR" | "KUBE_POD_CREATE_ERROR" | "KUBE_SERVICE_CREATE_ERROR" | "KUBE_INGRESS_CREATE_ERROR" | "KUBE_POD_FAILED_TO_START_ERROR" | "ensure-checking-existing-machines" | "found-multiple-failed-machine" | "maximun-retries-machine-creation" | GitAuthErrorCode | "unknown" | "project-bad-state" | "project-not-found" | "project-deleted" | "project-branch-not-found" | "project-branch-deleted" | "project-branch-no-session-id" | "project-repo-full-name-not-found" | "project-org-not-found" | "invalid-project-repo-url-already-in-use" | "no-available-regions" | "invalid-backup-without-volume-id" | "missing-app-with-machine-or-volume" | "update-branch-info-in-firebase" | "update-branch-app-name-in-firebase" | `machine-status-polling-${MachineState}` | `machine-image-exited-immediately` | `volume-not-found-${FlyVolumeState}` | "trying-to-remove-used-volume" | "missing-container-url" | "timeout" | "fatal:zod-validation-error" | `fatal:${string}`;
165
+ state: "ready";
166
+ message: string;
167
+ url: string;
168
+ status?: LaunchServerStatus;
169
+ }
170
+ export type MachineState =
171
+ | "unknown"
172
+ | "created"
173
+ | "starting"
174
+ | "started"
175
+ | "stopping"
176
+ | "stopped"
177
+ | "suspending"
178
+ | "suspended"
179
+ | "replacing"
180
+ | "destroying"
181
+ | "destroyed"
182
+ | "not-found"
183
+ | "running"
184
+ | "failed";
185
+ export type FlyVolumeState =
186
+ | "unknown"
187
+ | "creating"
188
+ | "created"
189
+ | "extending"
190
+ | "restoring"
191
+ | "enabling_remote_export"
192
+ | "hydrating"
193
+ | "recovering"
194
+ | "scheduling_destroy"
195
+ | "pending_destroy"
196
+ | "failed";
197
+ export type GitAuthErrorCode =
198
+ | "git-auth-failed"
199
+ | "git-auth-failed-root-repo"
200
+ | "git-auth-failed-folder-added-by"
201
+ | "git-auth-failed-folder-created-by"
202
+ | "git-auth-failed-repo-not-found"
203
+ | "git-auth-failed-repo-renamed"
204
+ | "git-auth-failed-folder-server-token"
205
+ | "git-auth-failed-root-repo-server-token"
206
+ | "git-auth-failed-ghes-unreachable";
207
+ export type EnsureContainerErrorCode =
208
+ | "FAILED_TO_START_MACHINE_ERROR"
209
+ | "FLY_APP_CHECK_ERROR"
210
+ | "FLY_CAPACITY_ERROR"
211
+ | "FLY_PERMISSIONS_TOKEN_ERROR"
212
+ | "FLY_VOLUME_CREATE_ERROR"
213
+ | "FLY_VOLUME_FORK_ERROR"
214
+ | "FLY_VOLUME_DELETE_RECENTLY_FORKED_ERROR"
215
+ | "FLY_MACHINE_CREATE_ERROR"
216
+ | "FLY_VOLUME_CHECK_ERROR"
217
+ | "FLY_NON_MOUNTABLE_VOLUME_ERROR"
218
+ | "FLY_DEPRECATED_REGION_ERROR"
219
+ | "FLY_VOLUME_NOT_FOUND"
220
+ | "FLY_MACHINE_LIMIT_ERROR"
221
+ | "KUBE_CAPACITY_ERROR"
222
+ | "KUBE_PERMISSIONS_ERROR"
223
+ | "KUBE_POD_LIMIT_ERROR"
224
+ | "KUBE_RESOURCE_QUOTA_ERROR"
225
+ | "KUBE_NAMESPACE_CHECK_ERROR"
226
+ | "KUBE_PVC_CREATE_ERROR"
227
+ | "KUBE_PVC_CHECK_ERROR"
228
+ | "KUBE_POD_CREATE_ERROR"
229
+ | "KUBE_SERVICE_CREATE_ERROR"
230
+ | "KUBE_INGRESS_CREATE_ERROR"
231
+ | "KUBE_POD_FAILED_TO_START_ERROR"
232
+ | "ensure-checking-existing-machines"
233
+ | "found-multiple-failed-machine"
234
+ | "maximun-retries-machine-creation"
235
+ | GitAuthErrorCode
236
+ | "unknown"
237
+ | "project-bad-state"
238
+ | "project-not-found"
239
+ | "project-deleted"
240
+ | "project-branch-not-found"
241
+ | "project-branch-deleted"
242
+ | "project-branch-no-session-id"
243
+ | "project-repo-full-name-not-found"
244
+ | "project-org-not-found"
245
+ | "invalid-project-repo-url-already-in-use"
246
+ | "no-available-regions"
247
+ | "invalid-backup-without-volume-id"
248
+ | "missing-app-with-machine-or-volume"
249
+ | "update-branch-info-in-firebase"
250
+ | "update-branch-app-name-in-firebase"
251
+ | `machine-status-polling-${MachineState}`
252
+ | `machine-image-exited-immediately`
253
+ | `volume-not-found-${FlyVolumeState}`
254
+ | "trying-to-remove-used-volume"
255
+ | "missing-container-url"
256
+ | "timeout"
257
+ | "fatal:zod-validation-error"
258
+ | `fatal:${string}`;
151
259
  export interface ErrorStateMessage extends BaseMessage {
152
- state: "error";
153
- message: string;
154
- error: string;
155
- code: EnsureContainerErrorCode;
156
- causeError: string;
260
+ state: "error";
261
+ message: string;
262
+ error: string;
263
+ code: EnsureContainerErrorCode;
264
+ causeError: string;
157
265
  }
158
266
  export interface CleanupCompletedMessage extends BaseMessage {
159
- state: "cleanupCompleted";
160
- message: string;
267
+ state: "cleanupCompleted";
268
+ message: string;
161
269
  }
162
270
  /**
163
271
  * Messages sent by the container orchestrator.
164
272
  */
165
- export type ProjectsChunkMessage = InitializingMessage | FetchingGithubTokenMessage | FetchingFusionKeyMessage | CheckingAppMessage | CleaningUpAppMessage | CreatingAppMessage | CheckingIPMessage | AllocatingIPMessage | CheckingMachineMessage | CheckingVolumeMessage | ForkingVolumeMessage | RetryingWithNewRegionMessage | WaitingBeforePollingMessage | PollingMachineStatusMessage | WarningStateMessage | PingMessage | DebugMessage | ErrorMessage | InfoMessage | WarningMessage | MachineStatusMessage | LogsMessage | ConfigStatusMessage | AppCreatedMessage | MachineCreatedMessage | IpAllocatedMessage | VolumeForkedMessage | ReadyMessage | ErrorStateMessage | CleanupCompletedMessage;
273
+ export type ProjectsChunkMessage =
274
+ | InitializingMessage
275
+ | FetchingGithubTokenMessage
276
+ | FetchingFusionKeyMessage
277
+ | CheckingAppMessage
278
+ | CleaningUpAppMessage
279
+ | CreatingAppMessage
280
+ | CheckingIPMessage
281
+ | AllocatingIPMessage
282
+ | CheckingMachineMessage
283
+ | CheckingVolumeMessage
284
+ | ForkingVolumeMessage
285
+ | RetryingWithNewRegionMessage
286
+ | WaitingBeforePollingMessage
287
+ | PollingMachineStatusMessage
288
+ | WarningStateMessage
289
+ | PingMessage
290
+ | DebugMessage
291
+ | ErrorMessage
292
+ | InfoMessage
293
+ | WarningMessage
294
+ | MachineStatusMessage
295
+ | LogsMessage
296
+ | ConfigStatusMessage
297
+ | AppCreatedMessage
298
+ | MachineCreatedMessage
299
+ | IpAllocatedMessage
300
+ | VolumeForkedMessage
301
+ | ReadyMessage
302
+ | ErrorStateMessage
303
+ | CleanupCompletedMessage;
166
304
  export interface GitConfig {
167
- url: string;
168
- provider: "github" | "bitbucket" | "gitlab" | "azure" | "unknown";
169
- token: string | undefined;
305
+ url: string;
306
+ provider: "github" | "bitbucket" | "gitlab" | "azure" | "unknown";
307
+ token: string | undefined;
170
308
  }
171
309
  export type GitConfigs = Record<string, GitConfig>;
172
310
  export declare const EXAMPLE_REPOS: string[];
@@ -174,121 +312,130 @@ export declare const STARTER_REPO = "BuilderIO/fusion-starter";
174
312
  export declare const EXAMPLE_OR_STARTER_REPOS: string[];
175
313
  export declare const EXAMPLE_OR_STARTER_REPOS_URLS: string[];
176
314
  export interface GitBackupUploadUrlResult {
177
- signedUrl: string;
178
- filePath: string;
179
- expiresAt: string;
315
+ signedUrl: string;
316
+ filePath: string;
317
+ expiresAt: string;
180
318
  }
181
319
  export interface GitBackupUploadUrlOptions {
182
- projectId: string;
183
- branchName: string;
184
- size: number;
185
- partial: boolean;
186
- contentMd5: string;
320
+ projectId: string;
321
+ branchName: string;
322
+ size: number;
323
+ partial: boolean;
324
+ contentMd5: string;
187
325
  }
188
326
  export interface GitBackupDownloadUrlOptions {
189
- spaceId: string;
190
- projectId: string;
191
- branchName: string;
192
- partial: boolean;
327
+ spaceId: string;
328
+ projectId: string;
329
+ branchName: string;
330
+ partial: boolean;
193
331
  }
194
332
  export type ForcedBackup = "offline-full" | "offline" | undefined;
195
333
  export interface GitBackupRecordOptions {
196
- projectId: string;
197
- branchName: string;
198
- size: number;
199
- gitBranchName: string;
200
- initialBranch: string;
201
- initialCommitHash: string | undefined;
202
- lastCommitHash: string;
203
- partial: boolean;
204
- empty: boolean;
205
- status: "completed";
206
- contentMd5?: string;
207
- repoUrl: string;
208
- version: "v1" | "v2";
209
- forced: ForcedBackup;
210
- metadata?: Record<string, string | string[] | undefined>;
334
+ projectId: string;
335
+ branchName: string;
336
+ size: number;
337
+ gitBranchName: string;
338
+ initialBranch: string;
339
+ initialCommitHash: string | undefined;
340
+ lastCommitHash: string;
341
+ partial: boolean;
342
+ empty: boolean;
343
+ status: "completed";
344
+ contentMd5?: string;
345
+ repoUrl: string;
346
+ version: "v1" | "v2";
347
+ forced: ForcedBackup;
348
+ metadata?: Record<string, string | string[] | undefined>;
211
349
  }
212
350
  export interface GitBackupRecordResult {
213
- success: boolean;
351
+ success: boolean;
214
352
  }
215
353
  export interface CodegenSetLastCommit {
216
- projectId: string;
217
- branchName: string;
218
- lastCommitHash: string;
219
- clearSecondaryVolumeId: boolean;
354
+ projectId: string;
355
+ branchName: string;
356
+ lastCommitHash: string;
357
+ clearSecondaryVolumeId: boolean;
220
358
  }
221
359
  export interface CodegenRuntimeStatus {
222
- projectId: string;
223
- branchName: string;
224
- lastCommitHash?: string;
225
- clearSecondaryVolumeId?: boolean;
226
- lastServerState?: LaunchServerState;
227
- lastServerVersion?: string;
360
+ projectId: string;
361
+ branchName: string;
362
+ lastCommitHash?: string;
363
+ clearSecondaryVolumeId?: boolean;
364
+ lastServerState?: LaunchServerState;
365
+ lastServerVersion?: string;
228
366
  }
229
367
  export interface BackupGitRepoResultValid {
230
- success: true;
231
- partial: boolean;
232
- repoUrl: string;
233
- empty: boolean;
234
- lastCommitHash: string;
235
- backupRef: string | undefined;
368
+ success: true;
369
+ partial: boolean;
370
+ repoUrl: string;
371
+ empty: boolean;
372
+ lastCommitHash: string;
373
+ backupRef: string | undefined;
236
374
  }
237
375
  export interface BackupGitRepoResultInvalid {
238
- success: false;
239
- reason: "project_removed";
240
- }
241
- export type BackupGitRepoResult = BackupGitRepoResultValid | BackupGitRepoResultInvalid;
242
- export type ShutdownResponse = {
243
- success: true;
244
- message: string;
245
- skipped: boolean;
246
- reason: string;
247
- } | {
248
- success: false;
249
- message?: string;
250
- skipped?: boolean;
251
- reason?: string;
252
- error?: Error;
253
- } | BackupGitRepoResult;
376
+ success: false;
377
+ reason: "project_removed";
378
+ }
379
+ export type BackupGitRepoResult =
380
+ | BackupGitRepoResultValid
381
+ | BackupGitRepoResultInvalid;
382
+ export type ShutdownResponse =
383
+ | {
384
+ success: true;
385
+ message: string;
386
+ skipped: boolean;
387
+ reason: string;
388
+ }
389
+ | {
390
+ success: false;
391
+ message?: string;
392
+ skipped?: boolean;
393
+ reason?: string;
394
+ error?: Error;
395
+ }
396
+ | BackupGitRepoResult;
254
397
  export type ShutdownResponseSerialized = Omit<ShutdownResponse, "error"> & {
255
- error?: string;
398
+ error?: string;
256
399
  };
257
400
  export type SetupDependency = SetupMiseDependency | SetupScriptDependency;
258
401
  export interface SetupMiseDependency {
259
- key: string;
260
- type: "mise";
261
- tool: string;
262
- version?: string;
402
+ key: string;
403
+ type: "mise";
404
+ tool: string;
405
+ version?: string;
263
406
  }
264
407
  export interface SetupScriptDependency {
265
- key: string;
266
- type: "script";
267
- name: string;
268
- script: string;
269
- }
270
- export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
408
+ key: string;
409
+ type: "script";
410
+ name: string;
411
+ script: string;
412
+ }
413
+ export type FusionExecutionEnvironment =
414
+ | "containerized"
415
+ | "container-less"
416
+ | "cloud"
417
+ | "cloud-v2";
271
418
  export interface PartialBranchData {
272
- name?: string;
273
- createdBy: string;
274
- friendlyName: string;
275
- isDefault: boolean;
276
- isPublic: boolean;
277
- lockedFusionEnvironment?: FusionExecutionEnvironment;
278
- metadata?: BranchMetadata;
279
- backup?: BranchBackup;
280
- gitAiBranch?: string | null;
281
- lastCommitHash?: string | null;
282
- lastCommitDate?: number | null;
283
- commitMode?: CommitMode;
284
- useHomeDir?: boolean;
285
- checkoutBranch?: string | null;
286
- /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
287
- isFork?: boolean | null;
288
- cloneFrom?: {
289
- projectId: string;
290
- branchName: string;
291
- };
419
+ name?: string;
420
+ createdBy: string;
421
+ friendlyName: string;
422
+ isDefault: boolean;
423
+ isPublic: boolean;
424
+ lockedFusionEnvironment?: FusionExecutionEnvironment;
425
+ metadata?: BranchMetadata;
426
+ backup?: BranchBackup;
427
+ gitAiBranch?: string | null;
428
+ lastCommitHash?: string | null;
429
+ lastCommitDate?: number | null;
430
+ commitMode?: CommitMode;
431
+ useHomeDir?: boolean;
432
+ checkoutBranch?: string | null;
433
+ /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
434
+ isFork?: boolean | null;
435
+ cloneFrom?: {
436
+ projectId: string;
437
+ branchName: string;
438
+ };
292
439
  }
293
440
  export type EntityState = "active" | "deleted" | "archived";
294
441
  /**
@@ -296,115 +443,117 @@ export type EntityState = "active" | "deleted" | "archived";
296
443
  * This type documents the integration context that can be attached to a branch.
297
444
  */
298
445
  export interface BranchMetadata {
299
- /** How the branch was created (e.g., "slack", "jira", "api", "cli") */
300
- createdVia?: string;
301
- /** JIRA issue key (e.g., "PROJ-123") - used to link back to the JIRA ticket in PR descriptions */
302
- jiraIssueKey?: string;
303
- /** JIRA cloud ID - UUID identifier for the Atlassian cloud instance */
304
- jiraCloudId?: string;
305
- /** JIRA site name - the subdomain used in the JIRA URL (e.g., "mycompany" for mycompany.atlassian.net) */
306
- jiraSiteName?: string;
307
- /** JIRA issue ID - internal JIRA identifier */
308
- jiraIssueId?: string;
309
- /** Slack team/workspace ID - used to ensure deep links open in the correct workspace for multi-workspace users */
310
- slackTeamId?: string;
311
- /** Slack channel ID - used to link back to the Slack thread in PR descriptions */
312
- slackChannelId?: string;
313
- /** Slack thread timestamp - used to construct the Slack thread URL */
314
- slackThreadTs?: string;
315
- [key: string]: unknown;
316
- }
317
- export type PRStatus = "open" | "closed" | "merged" | "draft";
446
+ /** How the branch was created (e.g., "slack", "jira", "api", "cli") */
447
+ createdVia?: string;
448
+ /** JIRA issue key (e.g., "PROJ-123") - used to link back to the JIRA ticket in PR descriptions */
449
+ jiraIssueKey?: string;
450
+ /** JIRA cloud ID - UUID identifier for the Atlassian cloud instance */
451
+ jiraCloudId?: string;
452
+ /** JIRA site name - the subdomain used in the JIRA URL (e.g., "mycompany" for mycompany.atlassian.net) */
453
+ jiraSiteName?: string;
454
+ /** JIRA issue ID - internal JIRA identifier */
455
+ jiraIssueId?: string;
456
+ /** Slack team/workspace ID - used to ensure deep links open in the correct workspace for multi-workspace users */
457
+ slackTeamId?: string;
458
+ /** Slack channel ID - used to link back to the Slack thread in PR descriptions */
459
+ slackChannelId?: string;
460
+ /** Slack thread timestamp - used to construct the Slack thread URL */
461
+ slackThreadTs?: string;
462
+ [key: string]: unknown;
463
+ }
464
+ export type PRStatus = "open" | "closed" | "merged" | "draft" | "approved";
318
465
  interface BranchSharedData {
319
- appName?: string | null;
320
- prNumber?: number | null;
321
- prUrl?: string | null;
322
- prStatus?: PRStatus;
323
- machineId?: string | null;
324
- lastMachineIdRemovedAt?: number | null;
325
- volumeId?: string | null;
326
- secondaryVolumeId?: string | null;
327
- volumeName?: string | null;
328
- gitAiBranch?: string | null;
329
- lastCommitHash?: string | null;
330
- lastCommitDate?: number | null;
331
- lastServerState?: LaunchServerState | null;
332
- lastServerStateDate?: number | null;
333
- lastServerVersion?: string | null;
334
- name?: string;
335
- agentType?: string | null;
336
- createdBy?: string;
337
- isPublic?: boolean;
338
- isDefault?: boolean;
339
- friendlyName?: string;
340
- useHomeDir?: boolean;
341
- useCloudHomeDir?: boolean;
342
- ipv4?: {
343
- address: string | null;
344
- allocated: boolean | null;
345
- } | null;
346
- ipv6?: {
347
- address: string | null;
348
- allocated: boolean | null;
349
- } | null;
350
- backup?: BranchBackup;
351
- metadata?: BranchMetadata;
352
- needsCleanup?: boolean;
353
- /** @deprecated Use `state` field instead. Kept for backwards compatibility. */
354
- deleted?: boolean;
355
- /** MIGRATION: accepts both string and number during migration period */
356
- deletedAt?: InMigrationDateNullable;
357
- deletedBy?: string;
358
- kubePodName?: string | null;
359
- kubeNamespace?: string | null;
360
- kubePvcName?: string | null;
361
- kubeHostname?: string | null;
362
- checkoutBranch?: string | null;
363
- /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
364
- isFork?: boolean | null;
365
- vscodeTunnelUrl?: string | null;
366
- vscodeTunnelName?: string | null;
367
- vscodeTunnelExpiresAt?: string | null;
368
- commitMode?: CommitMode;
369
- /** Timestamp when an AI agent started activity on this branch, null when inactive (in milliseconds since epoch) */
370
- lastAgentActivityAt?: number | null;
371
- /** Timestamp of last activity on this branch - includes both agent and user activity (in milliseconds since epoch) */
372
- lastActivityAt?: number;
466
+ appName?: string | null;
467
+ prNumber?: number | null;
468
+ prUrl?: string | null;
469
+ prStatus?: PRStatus;
470
+ machineId?: string | null;
471
+ lastMachineIdRemovedAt?: number | null;
472
+ volumeId?: string | null;
473
+ secondaryVolumeId?: string | null;
474
+ volumeName?: string | null;
475
+ gitAiBranch?: string | null;
476
+ lastCommitHash?: string | null;
477
+ lastCommitDate?: number | null;
478
+ lastServerState?: LaunchServerState | null;
479
+ lastServerStateDate?: number | null;
480
+ lastServerVersion?: string | null;
481
+ name?: string;
482
+ agentType?: string | null;
483
+ createdBy?: string;
484
+ isPublic?: boolean;
485
+ isDefault?: boolean;
486
+ friendlyName?: string;
487
+ useHomeDir?: boolean;
488
+ useCloudHomeDir?: boolean;
489
+ ipv4?: {
490
+ address: string | null;
491
+ allocated: boolean | null;
492
+ } | null;
493
+ ipv6?: {
494
+ address: string | null;
495
+ allocated: boolean | null;
496
+ } | null;
497
+ backup?: BranchBackup;
498
+ metadata?: BranchMetadata;
499
+ needsCleanup?: boolean;
500
+ /** @deprecated Use `state` field instead. Kept for backwards compatibility. */
501
+ deleted?: boolean;
502
+ /** MIGRATION: accepts both string and number during migration period */
503
+ deletedAt?: InMigrationDateNullable;
504
+ deletedBy?: string;
505
+ kubePodName?: string | null;
506
+ kubeNamespace?: string | null;
507
+ kubePvcName?: string | null;
508
+ kubeHostname?: string | null;
509
+ checkoutBranch?: string | null;
510
+ /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
511
+ isFork?: boolean | null;
512
+ vscodeTunnelUrl?: string | null;
513
+ vscodeTunnelName?: string | null;
514
+ vscodeTunnelExpiresAt?: string | null;
515
+ commitMode?: CommitMode;
516
+ /** Timestamp when an AI agent started activity on this branch, null when inactive (in milliseconds since epoch) */
517
+ lastAgentActivityAt?: number | null;
518
+ /** Timestamp of last activity on this branch - includes both agent and user activity (in milliseconds since epoch) */
519
+ lastActivityAt?: number;
373
520
  }
374
521
  /**
375
522
  * fields that are required in the new branch format, but optional in the legacy branch format.
376
523
  */
377
524
  interface RequiredBranchSharedData {
378
- /** The state of the branch. Use `isBranchDeleted()` helper for backwards-compatible checks. */
379
- state: EntityState;
380
- lockedFusionEnvironment: FusionExecutionEnvironment;
381
- id: string;
382
- sessionId: string;
383
- /** MIGRATION: accepts both string and number during migration period */
384
- createdAt: InMigrationDate;
385
- /** MIGRATION: accepts both string and number during migration period */
386
- updatedAt: InMigrationDate;
387
- lastUpdatedAt: number;
525
+ /** The state of the branch. Use `isBranchDeleted()` helper for backwards-compatible checks. */
526
+ state: EntityState;
527
+ lockedFusionEnvironment: FusionExecutionEnvironment;
528
+ id: string;
529
+ sessionId: string;
530
+ /** MIGRATION: accepts both string and number during migration period */
531
+ createdAt: InMigrationDate;
532
+ /** MIGRATION: accepts both string and number during migration period */
533
+ updatedAt: InMigrationDate;
534
+ lastUpdatedAt: number;
388
535
  }
389
536
  /**
390
537
  * LegacyBranch represents branch data as stored in the nested project.branches field.
391
538
  * This type does NOT include projectId or legacyId as those don't exist in the legacy format.
392
539
  */
393
- export interface LegacyBranch extends BranchSharedData, Partial<RequiredBranchSharedData> {
394
- preRecoveryData?: Partial<LegacyBranch> & {
395
- recoveryDate: Date;
396
- };
540
+ export interface LegacyBranch
541
+ extends BranchSharedData,
542
+ Partial<RequiredBranchSharedData> {
543
+ preRecoveryData?: Partial<LegacyBranch> & {
544
+ recoveryDate: Date;
545
+ };
397
546
  }
398
547
  /**
399
548
  * NewBranch represents branch data as stored in the standalone branches collection.
400
549
  * Extends LegacyBranch with required projectId, name, and optional legacyId fields.
401
550
  */
402
551
  export interface NewBranch extends BranchSharedData, RequiredBranchSharedData {
403
- ownerId: string;
404
- projectId: string;
405
- name: string;
406
- /** Legacy ID for mapping to project.branches[branchName] format: ${projectId}-${branchName} */
407
- legacyId: string;
552
+ ownerId: string;
553
+ projectId: string;
554
+ name: string;
555
+ /** Legacy ID for mapping to project.branches[branchName] format: ${projectId}-${branchName} */
556
+ legacyId: string;
408
557
  }
409
558
  /**
410
559
  * Branch is a union type that can represent either a legacy branch or a new branch.
@@ -415,140 +564,140 @@ export declare const checkIsNewBranch: (branch: Branch) => branch is NewBranch;
415
564
  export type CpuKind = "performance" | "standard" | "shared";
416
565
  export type MachineAutoStop = "stop" | "off" | "suspend";
417
566
  export interface ProjectRolePermissions {
418
- view?: boolean;
419
- editCode?: boolean;
420
- sendPullRequests?: boolean;
421
- createBranches?: boolean;
422
- modifyMcpServers?: boolean;
423
- modifyWorkflowIntegrations?: boolean;
424
- modifyProjectSettings?: boolean;
567
+ view?: boolean;
568
+ editCode?: boolean;
569
+ sendPullRequests?: boolean;
570
+ createBranches?: boolean;
571
+ modifyMcpServers?: boolean;
572
+ modifyWorkflowIntegrations?: boolean;
573
+ modifyProjectSettings?: boolean;
425
574
  }
426
575
  export interface ProjectAccessControl {
427
- roles: Record<string, ProjectRolePermissions | null>;
428
- users: Record<string, ProjectRolePermissions>;
576
+ roles: Record<string, ProjectRolePermissions | null>;
577
+ users: Record<string, ProjectRolePermissions>;
429
578
  }
430
579
  export interface Project {
431
- id: string;
432
- name: string;
433
- ownerId: string;
434
- repoFullName: string | undefined;
435
- repoProvider: string;
436
- repoProtocol: string | undefined;
437
- repoDescription?: string;
438
- repoPrivate: boolean;
439
- repoUrl: string | undefined;
440
- /** MIGRATION: accepts both string and number during migration period */
441
- createdDate: InMigrationDate;
442
- /** MIGRATION: accepts both string and number during migration period */
443
- updatedAt: InMigrationDate;
444
- pinned?: boolean;
445
- archived?: boolean;
446
- createdBy: string;
447
- checkRunCounts?: Record<string, number>;
448
- repoAddedBy?: string;
449
- pipelineCounts?: Record<string, number>;
450
- needSetup?: boolean;
451
- projectType?: "app" | "repo-indexing";
452
- domains?: string[];
453
- accessMode?: "public" | "private";
454
- projectAccess?: ProjectAccessControl;
455
- settings: {
456
- isNativeApp?: boolean;
457
- autoDetectDevServer?: boolean;
458
- autoDetectDevServerPatterns?: string[];
459
- fusionEnvironment?: FusionExecutionEnvironment;
460
- devServerPort?: number;
461
- devServerUrl?: string;
462
- refreshPreview?: boolean;
463
- installCommand?: string;
464
- validateCommand?: string;
465
- proxyOrigin?: string;
466
- proxyDefaultOrigin?: string;
467
- gitBranchNamingStrategy?: "ai-session" | "branch-name" | "custom";
468
- setupDependencies?: SetupDependency[];
469
- gitBranchNamingCustom?: string;
470
- askUserForBranchName?: boolean;
471
- devServerCommand?: string;
472
- cpuKind?: CpuKind;
473
- cpus?: 1 | 2 | 4;
474
- memory?: 2048 | 4096 | 8192 | 16384;
475
- /** @deprecated */
476
- memoryLimit?: 1024 | 2048 | 4096 | 8192 | 16384;
477
- autoStop?: MachineAutoStop;
478
- mainBranchName?: string;
479
- minMachinesRunning?: number;
480
- volumeSize?: 5 | 10 | 12 | 15 | 20;
481
- includePath?: string;
482
- includePatterns?: string[];
483
- environmentVariables?: EnvironmentVariable[];
484
- fileOverrides?: FileOverride[];
485
- customInstructions?: CustomInstruction[];
486
- customAgents?: CustomAgentDefinition[];
487
- commitMode?: CommitMode;
488
- defaultBranchType?: "shared" | "private";
489
- dockerImagePath?: string;
490
- nodeVersion?: string;
491
- designSystems?: string[];
492
- useNI?: boolean;
493
- folders?: Array<{
494
- name: string;
495
- remoteUrl: string;
496
- mainBranchName?: string;
497
- includePath?: string;
498
- addedBy?: string;
499
- repoProvider?: string;
500
- repoProtocol?: string;
501
- }>;
502
- agentsMD?: string;
503
- initializationCommand?: string;
504
- repoSubpath?: string;
505
- recommendedRoot?: string;
506
- https?: boolean;
507
- localHttpsDomain?: string;
508
- browserAutomation?: {
509
- backgroundAgents?: boolean;
510
- instructions?: string;
511
- authUser?: string;
512
- authPassword?: string;
513
- };
514
- qaBot?: boolean;
515
- httpsServerKeyPath?: string;
516
- httpsServerCertPath?: string;
517
- httpsServerCaPath?: string;
518
- httpsServerKeyContent?: string;
519
- httpsServerCertContent?: string;
520
- httpsServerCaContent?: string;
521
- httpsServerPfx?: string;
522
- httpsServerPassphrase?: string;
523
- httpsServerSecureProtocol?: string;
524
- httpsServerSecureOptions?: number;
525
- httpsServerCiphers?: string;
526
- httpsServerHonorCipherOrder?: boolean;
527
- httpsServerRequestCert?: boolean;
528
- httpsServerRejectUnauthorized?: boolean;
529
- };
530
- screenshot: string | null;
531
- isExample?: boolean;
532
- isPublic?: boolean;
533
- snapshotVolume?: {
534
- volumeId: string;
535
- appName: string;
536
- createdAt: number;
537
- };
538
- isFromUserTemplate?: boolean;
539
- templateId?: string | null;
540
- localPath?: string | null;
541
- /** The state of the project. Use `isProjectDeleted()` helper for backwards-compatible checks. */
542
- state?: EntityState;
543
- /** MIGRATION: accepts both string and number during migration period */
544
- deletedAt?: InMigrationDateNullable;
545
- deletedBy?: string;
546
- /**
547
- * When true, branches are stored in the standalone `branches` collection
548
- * instead of embedded in project.branches field.
549
- * Defaults to false for backwards compatibility with existing projects.
550
- */
551
- useBranchesCollection?: boolean;
580
+ id: string;
581
+ name: string;
582
+ ownerId: string;
583
+ repoFullName: string | undefined;
584
+ repoProvider: string;
585
+ repoProtocol: string | undefined;
586
+ repoDescription?: string;
587
+ repoPrivate: boolean;
588
+ repoUrl: string | undefined;
589
+ /** MIGRATION: accepts both string and number during migration period */
590
+ createdDate: InMigrationDate;
591
+ /** MIGRATION: accepts both string and number during migration period */
592
+ updatedAt: InMigrationDate;
593
+ pinned?: boolean;
594
+ archived?: boolean;
595
+ createdBy: string;
596
+ checkRunCounts?: Record<string, number>;
597
+ repoAddedBy?: string;
598
+ pipelineCounts?: Record<string, number>;
599
+ needSetup?: boolean;
600
+ projectType?: "app" | "repo-indexing";
601
+ domains?: string[];
602
+ accessMode?: "public" | "private";
603
+ projectAccess?: ProjectAccessControl;
604
+ settings: {
605
+ isNativeApp?: boolean;
606
+ autoDetectDevServer?: boolean;
607
+ autoDetectDevServerPatterns?: string[];
608
+ fusionEnvironment?: FusionExecutionEnvironment;
609
+ devServerPort?: number;
610
+ devServerUrl?: string;
611
+ refreshPreview?: boolean;
612
+ installCommand?: string;
613
+ validateCommand?: string;
614
+ proxyOrigin?: string;
615
+ proxyDefaultOrigin?: string;
616
+ gitBranchNamingStrategy?: "ai-session" | "branch-name" | "custom";
617
+ setupDependencies?: SetupDependency[];
618
+ gitBranchNamingCustom?: string;
619
+ askUserForBranchName?: boolean;
620
+ devServerCommand?: string;
621
+ cpuKind?: CpuKind;
622
+ cpus?: 1 | 2 | 4;
623
+ memory?: 2048 | 4096 | 8192 | 16384;
624
+ /** @deprecated */
625
+ memoryLimit?: 1024 | 2048 | 4096 | 8192 | 16384;
626
+ autoStop?: MachineAutoStop;
627
+ mainBranchName?: string;
628
+ minMachinesRunning?: number;
629
+ volumeSize?: 5 | 10 | 12 | 15 | 20;
630
+ includePath?: string;
631
+ includePatterns?: string[];
632
+ environmentVariables?: EnvironmentVariable[];
633
+ fileOverrides?: FileOverride[];
634
+ customInstructions?: CustomInstruction[];
635
+ customAgents?: CustomAgentDefinition[];
636
+ commitMode?: CommitMode;
637
+ defaultBranchType?: "shared" | "private";
638
+ dockerImagePath?: string;
639
+ nodeVersion?: string;
640
+ designSystems?: string[];
641
+ useNI?: boolean;
642
+ folders?: Array<{
643
+ name: string;
644
+ remoteUrl: string;
645
+ mainBranchName?: string;
646
+ includePath?: string;
647
+ addedBy?: string;
648
+ repoProvider?: string;
649
+ repoProtocol?: string;
650
+ }>;
651
+ agentsMD?: string;
652
+ initializationCommand?: string;
653
+ repoSubpath?: string;
654
+ recommendedRoot?: string;
655
+ https?: boolean;
656
+ localHttpsDomain?: string;
657
+ browserAutomation?: {
658
+ backgroundAgents?: boolean;
659
+ instructions?: string;
660
+ authUser?: string;
661
+ authPassword?: string;
662
+ };
663
+ qaBot?: boolean;
664
+ httpsServerKeyPath?: string;
665
+ httpsServerCertPath?: string;
666
+ httpsServerCaPath?: string;
667
+ httpsServerKeyContent?: string;
668
+ httpsServerCertContent?: string;
669
+ httpsServerCaContent?: string;
670
+ httpsServerPfx?: string;
671
+ httpsServerPassphrase?: string;
672
+ httpsServerSecureProtocol?: string;
673
+ httpsServerSecureOptions?: number;
674
+ httpsServerCiphers?: string;
675
+ httpsServerHonorCipherOrder?: boolean;
676
+ httpsServerRequestCert?: boolean;
677
+ httpsServerRejectUnauthorized?: boolean;
678
+ };
679
+ screenshot: string | null;
680
+ isExample?: boolean;
681
+ isPublic?: boolean;
682
+ snapshotVolume?: {
683
+ volumeId: string;
684
+ appName: string;
685
+ createdAt: number;
686
+ };
687
+ isFromUserTemplate?: boolean;
688
+ templateId?: string | null;
689
+ localPath?: string | null;
690
+ /** The state of the project. Use `isProjectDeleted()` helper for backwards-compatible checks. */
691
+ state?: EntityState;
692
+ /** MIGRATION: accepts both string and number during migration period */
693
+ deletedAt?: InMigrationDateNullable;
694
+ deletedBy?: string;
695
+ /**
696
+ * When true, branches are stored in the standalone `branches` collection
697
+ * instead of embedded in project.branches field.
698
+ * Defaults to false for backwards compatibility with existing projects.
699
+ */
700
+ useBranchesCollection?: boolean;
552
701
  }
553
702
  /**
554
703
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
@@ -572,31 +721,31 @@ export declare const isBranchArchived: (branch: Branch) => boolean;
572
721
  */
573
722
  export declare const isProjectDeleted: (project: Project) => boolean;
574
723
  export interface ProjectWithBranches extends Project {
575
- branches: Record<string, Branch>;
724
+ branches: Record<string, Branch>;
576
725
  }
577
726
  export interface OrganizationPrivate {
578
- ownerId: string;
579
- id: string;
580
- installs?: {
581
- ids: number[];
582
- host: string;
583
- }[];
584
- createdAt: number;
585
- updatedAt: number;
727
+ ownerId: string;
728
+ id: string;
729
+ installs?: {
730
+ ids: number[];
731
+ host: string;
732
+ }[];
733
+ createdAt: number;
734
+ updatedAt: number;
586
735
  }
587
736
  export interface CreateProjectOptions {
588
- name?: string;
589
- repoFullName: string;
590
- repoProvider: string;
591
- repoProtocol?: string;
592
- repoDescription?: string;
593
- repoPrivate: boolean;
594
- repoUrl: string;
595
- needSetup: boolean;
596
- domains?: string[];
597
- settings?: Partial<Project["settings"]>;
598
- isPublic?: boolean;
599
- isExample?: boolean;
600
- templateId?: string;
737
+ name?: string;
738
+ repoFullName: string;
739
+ repoProvider: string;
740
+ repoProtocol?: string;
741
+ repoDescription?: string;
742
+ repoPrivate: boolean;
743
+ repoUrl: string;
744
+ needSetup: boolean;
745
+ domains?: string[];
746
+ settings?: Partial<Project["settings"]>;
747
+ isPublic?: boolean;
748
+ isExample?: boolean;
749
+ templateId?: string;
601
750
  }
602
751
  export {};