@hoststack.dev/sdk 0.7.0 → 0.8.1

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/dist/index.d.cts CHANGED
@@ -28,20 +28,38 @@ interface Service {
28
28
  createdAt: string;
29
29
  updatedAt: string;
30
30
  }
31
+ type ServiceType = 'web_service' | 'private_service' | 'worker' | 'cron_job' | 'static_site';
32
+ type ServicePlan = 'pico' | 'nano' | 'micro' | 'starter' | 'standard' | 'pro_standard' | 'pro_large';
31
33
  interface CreateServiceInput {
32
34
  name: string;
33
- type: string;
34
- projectId?: string;
35
+ type: ServiceType;
36
+ projectId: number;
35
37
  /**
36
38
  * v66 P5: bind the new service to a specific environment in the
37
39
  * project. Omit to default to the project's Production env. Find or
38
40
  * list envs with `client.environments.list(teamId, projectId)`.
39
41
  */
40
42
  environmentId?: number;
41
- gitUrl?: string;
43
+ /** Connect a previously-linked GitHub repo by id. Mutually exclusive with gitlabRepoId/bitbucketRepoId/dockerImage. */
44
+ githubRepoId?: number;
45
+ gitlabRepoId?: number;
46
+ bitbucketRepoId?: number;
42
47
  branch?: string;
48
+ rootDirectory?: string;
49
+ installCommand?: string;
43
50
  buildCommand?: string;
44
51
  startCommand?: string;
52
+ plan?: ServicePlan;
53
+ /** Cron expression — required when `type: 'cron_job'`. */
54
+ cronSchedule?: string;
55
+ /** Static-site build output path, e.g. `dist`. */
56
+ publishPath?: string;
57
+ /** Pre-built image to deploy instead of building from source. */
58
+ dockerImage?: string;
59
+ /** Runtime hint (`node`, `bun`, `python`, …). Auto-detected when omitted. */
60
+ runtime?: string;
61
+ autoDeploy?: boolean;
62
+ multistage?: boolean;
45
63
  }
46
64
  /**
47
65
  * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
@@ -171,7 +189,10 @@ interface Deploy {
171
189
  totalDurationMs?: number;
172
190
  }
173
191
  interface TriggerDeployInput {
174
- clearCache?: boolean;
192
+ /** Override the commit to build. Defaults to the tip of the service's tracked branch. */
193
+ commitHash?: string;
194
+ /** Override the branch to build. Defaults to the service's configured branch. */
195
+ branch?: string;
175
196
  }
176
197
  /** Managed database engines supported by HostStack. */
177
198
  type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
@@ -189,6 +210,10 @@ interface Database {
189
210
  projectId: number;
190
211
  diskSizeGb?: number;
191
212
  memoryMb?: number;
213
+ /** v89: 'standalone' for the default single-node path; 'patroni' for
214
+ * a row backed by a 3-node Patroni HA cluster. Only meaningful when
215
+ * `engine === 'postgres'`. */
216
+ pgEngineType?: 'standalone' | 'patroni';
192
217
  createdAt: string;
193
218
  updatedAt: string;
194
219
  }
@@ -212,11 +237,12 @@ interface UpdateDatabaseInput {
212
237
  diskSizeGb?: number;
213
238
  }
214
239
  interface DatabaseCredentials {
215
- host: string;
216
- port: number;
217
- username: string;
240
+ /** Null while the database is still provisioning. */
241
+ host: string | null;
242
+ port: number | null;
243
+ username: string | null;
218
244
  password: string;
219
- database: string;
245
+ databaseName: string;
220
246
  connectionUrl: string;
221
247
  }
222
248
  /**
@@ -241,7 +267,7 @@ interface CreateVolumeInput {
241
267
  name: string;
242
268
  /** In-container absolute path where the volume mounts. */
243
269
  mountPath: string;
244
- /** Disk size in GB. 1–100, default 1. Counts against your plan's
270
+ /** Disk size in GB. 1–1024, default 1. Counts against your plan's
245
271
  * storage quota and is metered for billing. */
246
272
  sizeGb?: number;
247
273
  }
@@ -260,16 +286,22 @@ interface Domain {
260
286
  }
261
287
  interface AddDomainInput {
262
288
  domain: string;
263
- serviceId?: string;
289
+ /** Numeric service id (required). Pass `IdInput` to the resource method instead if you have a publicId. */
290
+ serviceId: number;
291
+ /** Path-prefix routing — point one hostname at multiple services (e.g. `/api` → api svc, `/` → web svc). */
292
+ pathPrefix?: string | null;
264
293
  }
265
294
  interface UpdateDomainInput {
266
- serviceId?: string;
295
+ /** Promote this hostname to the service's primary domain (sets the canonical URL header). */
296
+ isPrimary?: boolean;
297
+ /** When set, the hostname serves a 301 redirect to this absolute URL instead of routing traffic. */
298
+ redirectTo?: string | null;
267
299
  }
268
300
  interface EnvVar {
269
301
  id: number;
270
- publicId: string;
271
302
  key: string;
272
303
  value: string;
304
+ target: EnvVarTarget;
273
305
  isSecret: boolean;
274
306
  }
275
307
  type EnvVarTarget = 'build' | 'runtime' | 'both';
@@ -280,7 +312,6 @@ interface CreateEnvVarInput {
280
312
  isSecret?: boolean;
281
313
  }
282
314
  interface UpdateEnvVarInput {
283
- key?: string;
284
315
  value?: string;
285
316
  target?: EnvVarTarget;
286
317
  isSecret?: boolean;
@@ -316,11 +347,34 @@ interface MeResponse {
316
347
  };
317
348
  stripeMode?: string;
318
349
  }
319
- interface ServiceMetrics {
320
- cpu: number;
321
- memory: number;
322
- network: number;
323
- requests: number;
350
+ /**
351
+ * A single point in a service metrics time series. Same shape used for
352
+ * the latest-snapshot and history endpoints.
353
+ */
354
+ interface ServiceMetricsPoint {
355
+ timestamp: string;
356
+ cpuPercent: number;
357
+ memoryUsedMb: number;
358
+ memoryLimitMb: number;
359
+ networkRxBytes: number;
360
+ networkTxBytes: number;
361
+ diskUsedMb: number;
362
+ }
363
+ /**
364
+ * Latest-snapshot response from `services.getMetrics`. `metrics` is null
365
+ * before the first agent sample lands; `serverOverview` is null when the
366
+ * service is not currently placed on a worker (suspended, between
367
+ * deploys, etc).
368
+ */
369
+ interface ServiceMetricsSnapshot {
370
+ metrics: ServiceMetricsPoint | null;
371
+ serverOverview: {
372
+ cpuPercent: number;
373
+ memoryUsedMb: number;
374
+ memoryLimitMb: number;
375
+ diskUsedMb: number;
376
+ containerCount: number;
377
+ } | null;
324
378
  }
325
379
  interface CronExecution {
326
380
  id: number;
@@ -365,8 +419,11 @@ declare class CronResource {
365
419
  declare class DatabasesResource {
366
420
  private client;
367
421
  constructor(client: HostStack);
368
- /** List all databases for a project. */
369
- list(teamId: IdInput, projectId: IdInput): Promise<{
422
+ /**
423
+ * List databases for the team. Pass `projectId` to scope to one
424
+ * project; omit it to list every database the team owns.
425
+ */
426
+ list(teamId: IdInput, projectId?: IdInput): Promise<{
370
427
  databases: Database[];
371
428
  }>;
372
429
  /** Get a single database by ID. */
@@ -413,6 +470,41 @@ declare class DatabasesResource {
413
470
  truncated: boolean;
414
471
  durationMs: number;
415
472
  }>;
473
+ /**
474
+ * v89 Phase 4: trigger a single-node → HA migration (Patroni 3-node
475
+ * cluster). The customer-facing database briefly goes read-only during
476
+ * the pg_dump → bootstrap → pg_restore. The standalone container stays
477
+ * running (read-only) for 24 h as a rollback target before being
478
+ * decommissioned automatically.
479
+ *
480
+ * Requires (server-side): PATRONI_ENABLED env on the deployment +
481
+ * `teams.ha_beta=true` on this team. Throws 403 otherwise.
482
+ *
483
+ * Returns 202 — the upgrade is async; poll `get(...)` until
484
+ * `pgEngineType === 'patroni'` + `status === 'available'` to confirm.
485
+ */
486
+ upgradeToHa(teamId: IdInput, databaseId: IdInput): Promise<void>;
487
+ /**
488
+ * v89 Phase 5: cluster topology + failover history for a Patroni-managed
489
+ * Postgres database. Returns 400 for standalone databases — call
490
+ * `get(...)` first if you need to branch.
491
+ */
492
+ getCluster(teamId: IdInput, databaseId: IdInput): Promise<{
493
+ members: Array<{
494
+ id: number;
495
+ memberRole: 'etcd' | 'primary-candidate' | 'replica' | 'proxy';
496
+ containerId: string;
497
+ workerHostId: number | null;
498
+ joinedAt: string;
499
+ leftAt: string | null;
500
+ }>;
501
+ failovers: Array<{
502
+ id: number;
503
+ createdAt: string;
504
+ oldLeader: string | null;
505
+ newLeader: string | null;
506
+ }>;
507
+ }>;
416
508
  }
417
509
 
418
510
  interface DeployListResponse {
@@ -758,10 +850,14 @@ declare class ServicesResource {
758
850
  suspend(teamId: IdInput, serviceId: IdInput): Promise<void>;
759
851
  /** Resume a suspended service. */
760
852
  resume(teamId: IdInput, serviceId: IdInput): Promise<void>;
761
- /** Get service metrics. */
762
- getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
763
- metrics: ServiceMetrics;
764
- }>;
853
+ /**
854
+ * Get the latest metrics snapshot for a service.
855
+ *
856
+ * Returns `metrics: null` before the first agent sample lands;
857
+ * `serverOverview: null` when the service is not currently placed
858
+ * (suspended, between deploys, etc).
859
+ */
860
+ getMetrics(teamId: IdInput, serviceId: IdInput): Promise<ServiceMetricsSnapshot>;
765
861
  /**
766
862
  * Get a metrics time series for a service.
767
863
  *
@@ -808,7 +904,7 @@ declare class ServicesResource {
808
904
  since?: string;
809
905
  until?: string;
810
906
  stream?: 'stdout' | 'stderr';
811
- level?: 'stdout' | 'stderr' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
907
+ level?: 'stdout' | 'stderr' | 'debug' | 'info' | 'warn' | 'error';
812
908
  search?: string;
813
909
  grep?: string;
814
910
  countOnly?: boolean;
@@ -909,10 +1005,6 @@ type ResolveScope = {
909
1005
  kind: 'volume';
910
1006
  teamId: number;
911
1007
  serviceId: number;
912
- } | {
913
- kind: 'envVar';
914
- teamId: number;
915
- serviceId: number;
916
1008
  } | {
917
1009
  kind: 'environment';
918
1010
  teamId: number;
@@ -970,16 +1062,29 @@ declare class HostStack {
970
1062
 
971
1063
  declare class HostStackError extends Error {
972
1064
  readonly statusCode: number;
973
- constructor(statusCode: number, message: string);
1065
+ /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
1066
+ readonly body: unknown;
1067
+ constructor(statusCode: number, message: string, body?: unknown);
974
1068
  }
975
1069
  declare class AuthenticationError extends HostStackError {
976
- constructor(message?: string);
1070
+ constructor(message?: string, body?: unknown);
1071
+ }
1072
+ declare class ForbiddenError extends HostStackError {
1073
+ constructor(message?: string, body?: unknown);
977
1074
  }
978
1075
  declare class NotFoundError extends HostStackError {
979
- constructor(message?: string);
1076
+ constructor(message?: string, body?: unknown);
1077
+ }
1078
+ declare class ConflictError extends HostStackError {
1079
+ constructor(message?: string, body?: unknown);
980
1080
  }
981
1081
  declare class RateLimitError extends HostStackError {
982
- constructor(message?: string);
1082
+ /**
1083
+ * Seconds to wait before retrying, parsed from the `Retry-After` response
1084
+ * header. `undefined` if the server didn't send one.
1085
+ */
1086
+ readonly retryAfter: number | undefined;
1087
+ constructor(message?: string, retryAfter?: number, body?: unknown);
983
1088
  }
984
1089
 
985
1090
  /**
@@ -1012,4 +1117,4 @@ declare function buildPaginationQuery(params?: PaginationParams): string;
1012
1117
  */
1013
1118
  declare function wrapArray<T>(items: T[], params?: PaginationParams): PaginatedResponse<T>;
1014
1119
 
1015
- export { type ActivityLogEntry, type AddDomainInput, AuthenticationError, type BulkSetEnvVarsInput, type CreateDatabaseInput, type CreateEnvVarInput, type CreateEnvironmentInput, type CreateProjectInput, type CreateServiceInput, type CronExecution, type Database, type DatabaseCredentials, type Deploy, type DeployListResponse, type DeployLogEntry, type Domain, type EnvVar, type Environment, HostStack, HostStackError, type HostStackOptions, type LogEntry$1 as LogEntry, type MeResponse, NotFoundError, type NotificationChannel, type NotificationChannelEvent, type NotificationChannelType, type PaginatedResponse, type PaginationParams, type Project, RateLimitError, type Service, type ServiceConfig, type ServiceMetrics, type StreamLogsOptions, type Team, type TriggerDeployInput, type UpdateDatabaseInput, type UpdateDomainInput, type UpdateEnvVarInput, type UpdateEnvironmentInput, type UpdateProjectInput, type UpdateServiceConfigInput, type UpdateServiceInput, type User, buildPaginationQuery, wrapArray };
1120
+ export { type ActivityLogEntry, type AddDomainInput, AuthenticationError, type BulkSetEnvVarsInput, ConflictError, type CreateDatabaseInput, type CreateEnvVarInput, type CreateEnvironmentInput, type CreateProjectInput, type CreateServiceInput, type CreateVolumeInput, type CronExecution, type Database, type DatabaseCredentials, type Deploy, type DeployListResponse, type DeployLogEntry, type Domain, type EnvVar, type Environment, ForbiddenError, HostStack, HostStackError, type HostStackOptions, type IdInput, type LogEntry$1 as LogEntry, type MeResponse, NotFoundError, type NotificationChannel, type NotificationChannelEvent, type NotificationChannelType, type PaginatedResponse, type PaginationParams, type Project, RateLimitError, type Service, type ServiceConfig, type ServiceMetricsPoint, type ServiceMetricsSnapshot, type ServicePlan, type ServiceType, type StreamLogsOptions, type Team, type TriggerDeployInput, type UpdateDatabaseInput, type UpdateDomainInput, type UpdateEnvVarInput, type UpdateEnvironmentInput, type UpdateProjectInput, type UpdateServiceConfigInput, type UpdateServiceInput, type UpdateVolumeInput, type User, type Volume, buildPaginationQuery, wrapArray };
package/dist/index.d.ts CHANGED
@@ -28,20 +28,38 @@ interface Service {
28
28
  createdAt: string;
29
29
  updatedAt: string;
30
30
  }
31
+ type ServiceType = 'web_service' | 'private_service' | 'worker' | 'cron_job' | 'static_site';
32
+ type ServicePlan = 'pico' | 'nano' | 'micro' | 'starter' | 'standard' | 'pro_standard' | 'pro_large';
31
33
  interface CreateServiceInput {
32
34
  name: string;
33
- type: string;
34
- projectId?: string;
35
+ type: ServiceType;
36
+ projectId: number;
35
37
  /**
36
38
  * v66 P5: bind the new service to a specific environment in the
37
39
  * project. Omit to default to the project's Production env. Find or
38
40
  * list envs with `client.environments.list(teamId, projectId)`.
39
41
  */
40
42
  environmentId?: number;
41
- gitUrl?: string;
43
+ /** Connect a previously-linked GitHub repo by id. Mutually exclusive with gitlabRepoId/bitbucketRepoId/dockerImage. */
44
+ githubRepoId?: number;
45
+ gitlabRepoId?: number;
46
+ bitbucketRepoId?: number;
42
47
  branch?: string;
48
+ rootDirectory?: string;
49
+ installCommand?: string;
43
50
  buildCommand?: string;
44
51
  startCommand?: string;
52
+ plan?: ServicePlan;
53
+ /** Cron expression — required when `type: 'cron_job'`. */
54
+ cronSchedule?: string;
55
+ /** Static-site build output path, e.g. `dist`. */
56
+ publishPath?: string;
57
+ /** Pre-built image to deploy instead of building from source. */
58
+ dockerImage?: string;
59
+ /** Runtime hint (`node`, `bun`, `python`, …). Auto-detected when omitted. */
60
+ runtime?: string;
61
+ autoDeploy?: boolean;
62
+ multistage?: boolean;
45
63
  }
46
64
  /**
47
65
  * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
@@ -171,7 +189,10 @@ interface Deploy {
171
189
  totalDurationMs?: number;
172
190
  }
173
191
  interface TriggerDeployInput {
174
- clearCache?: boolean;
192
+ /** Override the commit to build. Defaults to the tip of the service's tracked branch. */
193
+ commitHash?: string;
194
+ /** Override the branch to build. Defaults to the service's configured branch. */
195
+ branch?: string;
175
196
  }
176
197
  /** Managed database engines supported by HostStack. */
177
198
  type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
@@ -189,6 +210,10 @@ interface Database {
189
210
  projectId: number;
190
211
  diskSizeGb?: number;
191
212
  memoryMb?: number;
213
+ /** v89: 'standalone' for the default single-node path; 'patroni' for
214
+ * a row backed by a 3-node Patroni HA cluster. Only meaningful when
215
+ * `engine === 'postgres'`. */
216
+ pgEngineType?: 'standalone' | 'patroni';
192
217
  createdAt: string;
193
218
  updatedAt: string;
194
219
  }
@@ -212,11 +237,12 @@ interface UpdateDatabaseInput {
212
237
  diskSizeGb?: number;
213
238
  }
214
239
  interface DatabaseCredentials {
215
- host: string;
216
- port: number;
217
- username: string;
240
+ /** Null while the database is still provisioning. */
241
+ host: string | null;
242
+ port: number | null;
243
+ username: string | null;
218
244
  password: string;
219
- database: string;
245
+ databaseName: string;
220
246
  connectionUrl: string;
221
247
  }
222
248
  /**
@@ -241,7 +267,7 @@ interface CreateVolumeInput {
241
267
  name: string;
242
268
  /** In-container absolute path where the volume mounts. */
243
269
  mountPath: string;
244
- /** Disk size in GB. 1–100, default 1. Counts against your plan's
270
+ /** Disk size in GB. 1–1024, default 1. Counts against your plan's
245
271
  * storage quota and is metered for billing. */
246
272
  sizeGb?: number;
247
273
  }
@@ -260,16 +286,22 @@ interface Domain {
260
286
  }
261
287
  interface AddDomainInput {
262
288
  domain: string;
263
- serviceId?: string;
289
+ /** Numeric service id (required). Pass `IdInput` to the resource method instead if you have a publicId. */
290
+ serviceId: number;
291
+ /** Path-prefix routing — point one hostname at multiple services (e.g. `/api` → api svc, `/` → web svc). */
292
+ pathPrefix?: string | null;
264
293
  }
265
294
  interface UpdateDomainInput {
266
- serviceId?: string;
295
+ /** Promote this hostname to the service's primary domain (sets the canonical URL header). */
296
+ isPrimary?: boolean;
297
+ /** When set, the hostname serves a 301 redirect to this absolute URL instead of routing traffic. */
298
+ redirectTo?: string | null;
267
299
  }
268
300
  interface EnvVar {
269
301
  id: number;
270
- publicId: string;
271
302
  key: string;
272
303
  value: string;
304
+ target: EnvVarTarget;
273
305
  isSecret: boolean;
274
306
  }
275
307
  type EnvVarTarget = 'build' | 'runtime' | 'both';
@@ -280,7 +312,6 @@ interface CreateEnvVarInput {
280
312
  isSecret?: boolean;
281
313
  }
282
314
  interface UpdateEnvVarInput {
283
- key?: string;
284
315
  value?: string;
285
316
  target?: EnvVarTarget;
286
317
  isSecret?: boolean;
@@ -316,11 +347,34 @@ interface MeResponse {
316
347
  };
317
348
  stripeMode?: string;
318
349
  }
319
- interface ServiceMetrics {
320
- cpu: number;
321
- memory: number;
322
- network: number;
323
- requests: number;
350
+ /**
351
+ * A single point in a service metrics time series. Same shape used for
352
+ * the latest-snapshot and history endpoints.
353
+ */
354
+ interface ServiceMetricsPoint {
355
+ timestamp: string;
356
+ cpuPercent: number;
357
+ memoryUsedMb: number;
358
+ memoryLimitMb: number;
359
+ networkRxBytes: number;
360
+ networkTxBytes: number;
361
+ diskUsedMb: number;
362
+ }
363
+ /**
364
+ * Latest-snapshot response from `services.getMetrics`. `metrics` is null
365
+ * before the first agent sample lands; `serverOverview` is null when the
366
+ * service is not currently placed on a worker (suspended, between
367
+ * deploys, etc).
368
+ */
369
+ interface ServiceMetricsSnapshot {
370
+ metrics: ServiceMetricsPoint | null;
371
+ serverOverview: {
372
+ cpuPercent: number;
373
+ memoryUsedMb: number;
374
+ memoryLimitMb: number;
375
+ diskUsedMb: number;
376
+ containerCount: number;
377
+ } | null;
324
378
  }
325
379
  interface CronExecution {
326
380
  id: number;
@@ -365,8 +419,11 @@ declare class CronResource {
365
419
  declare class DatabasesResource {
366
420
  private client;
367
421
  constructor(client: HostStack);
368
- /** List all databases for a project. */
369
- list(teamId: IdInput, projectId: IdInput): Promise<{
422
+ /**
423
+ * List databases for the team. Pass `projectId` to scope to one
424
+ * project; omit it to list every database the team owns.
425
+ */
426
+ list(teamId: IdInput, projectId?: IdInput): Promise<{
370
427
  databases: Database[];
371
428
  }>;
372
429
  /** Get a single database by ID. */
@@ -413,6 +470,41 @@ declare class DatabasesResource {
413
470
  truncated: boolean;
414
471
  durationMs: number;
415
472
  }>;
473
+ /**
474
+ * v89 Phase 4: trigger a single-node → HA migration (Patroni 3-node
475
+ * cluster). The customer-facing database briefly goes read-only during
476
+ * the pg_dump → bootstrap → pg_restore. The standalone container stays
477
+ * running (read-only) for 24 h as a rollback target before being
478
+ * decommissioned automatically.
479
+ *
480
+ * Requires (server-side): PATRONI_ENABLED env on the deployment +
481
+ * `teams.ha_beta=true` on this team. Throws 403 otherwise.
482
+ *
483
+ * Returns 202 — the upgrade is async; poll `get(...)` until
484
+ * `pgEngineType === 'patroni'` + `status === 'available'` to confirm.
485
+ */
486
+ upgradeToHa(teamId: IdInput, databaseId: IdInput): Promise<void>;
487
+ /**
488
+ * v89 Phase 5: cluster topology + failover history for a Patroni-managed
489
+ * Postgres database. Returns 400 for standalone databases — call
490
+ * `get(...)` first if you need to branch.
491
+ */
492
+ getCluster(teamId: IdInput, databaseId: IdInput): Promise<{
493
+ members: Array<{
494
+ id: number;
495
+ memberRole: 'etcd' | 'primary-candidate' | 'replica' | 'proxy';
496
+ containerId: string;
497
+ workerHostId: number | null;
498
+ joinedAt: string;
499
+ leftAt: string | null;
500
+ }>;
501
+ failovers: Array<{
502
+ id: number;
503
+ createdAt: string;
504
+ oldLeader: string | null;
505
+ newLeader: string | null;
506
+ }>;
507
+ }>;
416
508
  }
417
509
 
418
510
  interface DeployListResponse {
@@ -758,10 +850,14 @@ declare class ServicesResource {
758
850
  suspend(teamId: IdInput, serviceId: IdInput): Promise<void>;
759
851
  /** Resume a suspended service. */
760
852
  resume(teamId: IdInput, serviceId: IdInput): Promise<void>;
761
- /** Get service metrics. */
762
- getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
763
- metrics: ServiceMetrics;
764
- }>;
853
+ /**
854
+ * Get the latest metrics snapshot for a service.
855
+ *
856
+ * Returns `metrics: null` before the first agent sample lands;
857
+ * `serverOverview: null` when the service is not currently placed
858
+ * (suspended, between deploys, etc).
859
+ */
860
+ getMetrics(teamId: IdInput, serviceId: IdInput): Promise<ServiceMetricsSnapshot>;
765
861
  /**
766
862
  * Get a metrics time series for a service.
767
863
  *
@@ -808,7 +904,7 @@ declare class ServicesResource {
808
904
  since?: string;
809
905
  until?: string;
810
906
  stream?: 'stdout' | 'stderr';
811
- level?: 'stdout' | 'stderr' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
907
+ level?: 'stdout' | 'stderr' | 'debug' | 'info' | 'warn' | 'error';
812
908
  search?: string;
813
909
  grep?: string;
814
910
  countOnly?: boolean;
@@ -909,10 +1005,6 @@ type ResolveScope = {
909
1005
  kind: 'volume';
910
1006
  teamId: number;
911
1007
  serviceId: number;
912
- } | {
913
- kind: 'envVar';
914
- teamId: number;
915
- serviceId: number;
916
1008
  } | {
917
1009
  kind: 'environment';
918
1010
  teamId: number;
@@ -970,16 +1062,29 @@ declare class HostStack {
970
1062
 
971
1063
  declare class HostStackError extends Error {
972
1064
  readonly statusCode: number;
973
- constructor(statusCode: number, message: string);
1065
+ /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
1066
+ readonly body: unknown;
1067
+ constructor(statusCode: number, message: string, body?: unknown);
974
1068
  }
975
1069
  declare class AuthenticationError extends HostStackError {
976
- constructor(message?: string);
1070
+ constructor(message?: string, body?: unknown);
1071
+ }
1072
+ declare class ForbiddenError extends HostStackError {
1073
+ constructor(message?: string, body?: unknown);
977
1074
  }
978
1075
  declare class NotFoundError extends HostStackError {
979
- constructor(message?: string);
1076
+ constructor(message?: string, body?: unknown);
1077
+ }
1078
+ declare class ConflictError extends HostStackError {
1079
+ constructor(message?: string, body?: unknown);
980
1080
  }
981
1081
  declare class RateLimitError extends HostStackError {
982
- constructor(message?: string);
1082
+ /**
1083
+ * Seconds to wait before retrying, parsed from the `Retry-After` response
1084
+ * header. `undefined` if the server didn't send one.
1085
+ */
1086
+ readonly retryAfter: number | undefined;
1087
+ constructor(message?: string, retryAfter?: number, body?: unknown);
983
1088
  }
984
1089
 
985
1090
  /**
@@ -1012,4 +1117,4 @@ declare function buildPaginationQuery(params?: PaginationParams): string;
1012
1117
  */
1013
1118
  declare function wrapArray<T>(items: T[], params?: PaginationParams): PaginatedResponse<T>;
1014
1119
 
1015
- export { type ActivityLogEntry, type AddDomainInput, AuthenticationError, type BulkSetEnvVarsInput, type CreateDatabaseInput, type CreateEnvVarInput, type CreateEnvironmentInput, type CreateProjectInput, type CreateServiceInput, type CronExecution, type Database, type DatabaseCredentials, type Deploy, type DeployListResponse, type DeployLogEntry, type Domain, type EnvVar, type Environment, HostStack, HostStackError, type HostStackOptions, type LogEntry$1 as LogEntry, type MeResponse, NotFoundError, type NotificationChannel, type NotificationChannelEvent, type NotificationChannelType, type PaginatedResponse, type PaginationParams, type Project, RateLimitError, type Service, type ServiceConfig, type ServiceMetrics, type StreamLogsOptions, type Team, type TriggerDeployInput, type UpdateDatabaseInput, type UpdateDomainInput, type UpdateEnvVarInput, type UpdateEnvironmentInput, type UpdateProjectInput, type UpdateServiceConfigInput, type UpdateServiceInput, type User, buildPaginationQuery, wrapArray };
1120
+ export { type ActivityLogEntry, type AddDomainInput, AuthenticationError, type BulkSetEnvVarsInput, ConflictError, type CreateDatabaseInput, type CreateEnvVarInput, type CreateEnvironmentInput, type CreateProjectInput, type CreateServiceInput, type CreateVolumeInput, type CronExecution, type Database, type DatabaseCredentials, type Deploy, type DeployListResponse, type DeployLogEntry, type Domain, type EnvVar, type Environment, ForbiddenError, HostStack, HostStackError, type HostStackOptions, type IdInput, type LogEntry$1 as LogEntry, type MeResponse, NotFoundError, type NotificationChannel, type NotificationChannelEvent, type NotificationChannelType, type PaginatedResponse, type PaginationParams, type Project, RateLimitError, type Service, type ServiceConfig, type ServiceMetricsPoint, type ServiceMetricsSnapshot, type ServicePlan, type ServiceType, type StreamLogsOptions, type Team, type TriggerDeployInput, type UpdateDatabaseInput, type UpdateDomainInput, type UpdateEnvVarInput, type UpdateEnvironmentInput, type UpdateProjectInput, type UpdateServiceConfigInput, type UpdateServiceInput, type UpdateVolumeInput, type User, type Volume, buildPaginationQuery, wrapArray };