@hoststack.dev/sdk 0.8.0 → 0.8.1

package/dist/index.d.cts

@@ -28,20 +28,38 @@ interface Service {
     createdAt: string;
     updatedAt: string;
 }
+type ServiceType = 'web_service' | 'private_service' | 'worker' | 'cron_job' | 'static_site';
+type ServicePlan = 'pico' | 'nano' | 'micro' | 'starter' | 'standard' | 'pro_standard' | 'pro_large';
 interface CreateServiceInput {
     name: string;
-    type: string;
-    projectId?: string;
+    type: ServiceType;
+    projectId: number;
     /**
      * v66 P5: bind the new service to a specific environment in the
      * project. Omit to default to the project's Production env. Find or
      * list envs with `client.environments.list(teamId, projectId)`.
      */
     environmentId?: number;
-    gitUrl?: string;
+    /** Connect a previously-linked GitHub repo by id. Mutually exclusive with gitlabRepoId/bitbucketRepoId/dockerImage. */
+    githubRepoId?: number;
+    gitlabRepoId?: number;
+    bitbucketRepoId?: number;
     branch?: string;
+    rootDirectory?: string;
+    installCommand?: string;
     buildCommand?: string;
     startCommand?: string;
+    plan?: ServicePlan;
+    /** Cron expression — required when `type: 'cron_job'`. */
+    cronSchedule?: string;
+    /** Static-site build output path, e.g. `dist`. */
+    publishPath?: string;
+    /** Pre-built image to deploy instead of building from source. */
+    dockerImage?: string;
+    /** Runtime hint (`node`, `bun`, `python`, …). Auto-detected when omitted. */
+    runtime?: string;
+    autoDeploy?: boolean;
+    multistage?: boolean;
 }
 /**
  * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
@@ -171,7 +189,10 @@ interface Deploy {
     totalDurationMs?: number;
 }
 interface TriggerDeployInput {
-    clearCache?: boolean;
+    /** Override the commit to build. Defaults to the tip of the service's tracked branch. */
+    commitHash?: string;
+    /** Override the branch to build. Defaults to the service's configured branch. */
+    branch?: string;
 }
 /** Managed database engines supported by HostStack. */
 type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
@@ -216,11 +237,12 @@ interface UpdateDatabaseInput {
     diskSizeGb?: number;
 }
 interface DatabaseCredentials {
-    host: string;
-    port: number;
-    username: string;
+    /** Null while the database is still provisioning. */
+    host: string | null;
+    port: number | null;
+    username: string | null;
     password: string;
-    database: string;
+    databaseName: string;
     connectionUrl: string;
 }
 /**
@@ -245,7 +267,7 @@ interface CreateVolumeInput {
     name: string;
     /** In-container absolute path where the volume mounts. */
     mountPath: string;
-    /** Disk size in GB. 1–100, default 1. Counts against your plan's
+    /** Disk size in GB. 1–1024, default 1. Counts against your plan's
      *  storage quota and is metered for billing. */
     sizeGb?: number;
 }
@@ -264,16 +286,22 @@ interface Domain {
 }
 interface AddDomainInput {
     domain: string;
-    serviceId?: string;
+    /** Numeric service id (required). Pass `IdInput` to the resource method instead if you have a publicId. */
+    serviceId: number;
+    /** Path-prefix routing — point one hostname at multiple services (e.g. `/api` → api svc, `/` → web svc). */
+    pathPrefix?: string | null;
 }
 interface UpdateDomainInput {
-    serviceId?: string;
+    /** Promote this hostname to the service's primary domain (sets the canonical URL header). */
+    isPrimary?: boolean;
+    /** When set, the hostname serves a 301 redirect to this absolute URL instead of routing traffic. */
+    redirectTo?: string | null;
 }
 interface EnvVar {
     id: number;
-    publicId: string;
     key: string;
     value: string;
+    target: EnvVarTarget;
     isSecret: boolean;
 }
 type EnvVarTarget = 'build' | 'runtime' | 'both';
@@ -284,7 +312,6 @@ interface CreateEnvVarInput {
     isSecret?: boolean;
 }
 interface UpdateEnvVarInput {
-    key?: string;
     value?: string;
     target?: EnvVarTarget;
     isSecret?: boolean;
@@ -320,11 +347,34 @@ interface MeResponse {
     };
     stripeMode?: string;
 }
-interface ServiceMetrics {
-    cpu: number;
-    memory: number;
-    network: number;
-    requests: number;
+/**
+ * A single point in a service metrics time series. Same shape used for
+ * the latest-snapshot and history endpoints.
+ */
+interface ServiceMetricsPoint {
+    timestamp: string;
+    cpuPercent: number;
+    memoryUsedMb: number;
+    memoryLimitMb: number;
+    networkRxBytes: number;
+    networkTxBytes: number;
+    diskUsedMb: number;
+}
+/**
+ * Latest-snapshot response from `services.getMetrics`. `metrics` is null
+ * before the first agent sample lands; `serverOverview` is null when the
+ * service is not currently placed on a worker (suspended, between
+ * deploys, etc).
+ */
+interface ServiceMetricsSnapshot {
+    metrics: ServiceMetricsPoint | null;
+    serverOverview: {
+        cpuPercent: number;
+        memoryUsedMb: number;
+        memoryLimitMb: number;
+        diskUsedMb: number;
+        containerCount: number;
+    } | null;
 }
 interface CronExecution {
     id: number;
@@ -369,8 +419,11 @@ declare class CronResource {
 declare class DatabasesResource {
     private client;
     constructor(client: HostStack);
-    /** List all databases for a project. */
-    list(teamId: IdInput, projectId: IdInput): Promise<{
+    /**
+     * List databases for the team. Pass `projectId` to scope to one
+     * project; omit it to list every database the team owns.
+     */
+    list(teamId: IdInput, projectId?: IdInput): Promise<{
         databases: Database[];
     }>;
     /** Get a single database by ID. */
@@ -797,10 +850,14 @@ declare class ServicesResource {
     suspend(teamId: IdInput, serviceId: IdInput): Promise<void>;
     /** Resume a suspended service. */
     resume(teamId: IdInput, serviceId: IdInput): Promise<void>;
-    /** Get service metrics. */
-    getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
-        metrics: ServiceMetrics;
-    }>;
+    /**
+     * Get the latest metrics snapshot for a service.
+     *
+     * Returns `metrics: null` before the first agent sample lands;
+     * `serverOverview: null` when the service is not currently placed
+     * (suspended, between deploys, etc).
+     */
+    getMetrics(teamId: IdInput, serviceId: IdInput): Promise<ServiceMetricsSnapshot>;
     /**
      * Get a metrics time series for a service.
      *
@@ -847,7 +904,7 @@ declare class ServicesResource {
         since?: string;
         until?: string;
         stream?: 'stdout' | 'stderr';
-        level?: 'stdout' | 'stderr' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+        level?: 'stdout' | 'stderr' | 'debug' | 'info' | 'warn' | 'error';
         search?: string;
         grep?: string;
         countOnly?: boolean;
@@ -948,10 +1005,6 @@ type ResolveScope = {
     kind: 'volume';
     teamId: number;
     serviceId: number;
-} | {
-    kind: 'envVar';
-    teamId: number;
-    serviceId: number;
 } | {
     kind: 'environment';
     teamId: number;
@@ -1009,16 +1062,29 @@ declare class HostStack {
 
 declare class HostStackError extends Error {
     readonly statusCode: number;
-    constructor(statusCode: number, message: string);
+    /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
+    readonly body: unknown;
+    constructor(statusCode: number, message: string, body?: unknown);
 }
 declare class AuthenticationError extends HostStackError {
-    constructor(message?: string);
+    constructor(message?: string, body?: unknown);
+}
+declare class ForbiddenError extends HostStackError {
+    constructor(message?: string, body?: unknown);
 }
 declare class NotFoundError extends HostStackError {
-    constructor(message?: string);
+    constructor(message?: string, body?: unknown);
+}
+declare class ConflictError extends HostStackError {
+    constructor(message?: string, body?: unknown);
 }
 declare class RateLimitError extends HostStackError {
-    constructor(message?: string);
+    /**
+     * Seconds to wait before retrying, parsed from the `Retry-After` response
+     * header. `undefined` if the server didn't send one.
+     */
+    readonly retryAfter: number | undefined;
+    constructor(message?: string, retryAfter?: number, body?: unknown);
 }
 
 /**
@@ -1051,4 +1117,4 @@ declare function buildPaginationQuery(params?: PaginationParams): string;
  */
 declare function wrapArray<T>(items: T[], params?: PaginationParams): PaginatedResponse<T>;
 
-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 };
+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

@@ -28,20 +28,38 @@ interface Service {
     createdAt: string;
     updatedAt: string;
 }
+type ServiceType = 'web_service' | 'private_service' | 'worker' | 'cron_job' | 'static_site';
+type ServicePlan = 'pico' | 'nano' | 'micro' | 'starter' | 'standard' | 'pro_standard' | 'pro_large';
 interface CreateServiceInput {
     name: string;
-    type: string;
-    projectId?: string;
+    type: ServiceType;
+    projectId: number;
     /**
      * v66 P5: bind the new service to a specific environment in the
      * project. Omit to default to the project's Production env. Find or
      * list envs with `client.environments.list(teamId, projectId)`.
      */
     environmentId?: number;
-    gitUrl?: string;
+    /** Connect a previously-linked GitHub repo by id. Mutually exclusive with gitlabRepoId/bitbucketRepoId/dockerImage. */
+    githubRepoId?: number;
+    gitlabRepoId?: number;
+    bitbucketRepoId?: number;
     branch?: string;
+    rootDirectory?: string;
+    installCommand?: string;
     buildCommand?: string;
     startCommand?: string;
+    plan?: ServicePlan;
+    /** Cron expression — required when `type: 'cron_job'`. */
+    cronSchedule?: string;
+    /** Static-site build output path, e.g. `dist`. */
+    publishPath?: string;
+    /** Pre-built image to deploy instead of building from source. */
+    dockerImage?: string;
+    /** Runtime hint (`node`, `bun`, `python`, …). Auto-detected when omitted. */
+    runtime?: string;
+    autoDeploy?: boolean;
+    multistage?: boolean;
 }
 /**
  * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
@@ -171,7 +189,10 @@ interface Deploy {
     totalDurationMs?: number;
 }
 interface TriggerDeployInput {
-    clearCache?: boolean;
+    /** Override the commit to build. Defaults to the tip of the service's tracked branch. */
+    commitHash?: string;
+    /** Override the branch to build. Defaults to the service's configured branch. */
+    branch?: string;
 }
 /** Managed database engines supported by HostStack. */
 type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
@@ -216,11 +237,12 @@ interface UpdateDatabaseInput {
     diskSizeGb?: number;
 }
 interface DatabaseCredentials {
-    host: string;
-    port: number;
-    username: string;
+    /** Null while the database is still provisioning. */
+    host: string | null;
+    port: number | null;
+    username: string | null;
     password: string;
-    database: string;
+    databaseName: string;
     connectionUrl: string;
 }
 /**
@@ -245,7 +267,7 @@ interface CreateVolumeInput {
     name: string;
     /** In-container absolute path where the volume mounts. */
     mountPath: string;
-    /** Disk size in GB. 1–100, default 1. Counts against your plan's
+    /** Disk size in GB. 1–1024, default 1. Counts against your plan's
      *  storage quota and is metered for billing. */
     sizeGb?: number;
 }
@@ -264,16 +286,22 @@ interface Domain {
 }
 interface AddDomainInput {
     domain: string;
-    serviceId?: string;
+    /** Numeric service id (required). Pass `IdInput` to the resource method instead if you have a publicId. */
+    serviceId: number;
+    /** Path-prefix routing — point one hostname at multiple services (e.g. `/api` → api svc, `/` → web svc). */
+    pathPrefix?: string | null;
 }
 interface UpdateDomainInput {
-    serviceId?: string;
+    /** Promote this hostname to the service's primary domain (sets the canonical URL header). */
+    isPrimary?: boolean;
+    /** When set, the hostname serves a 301 redirect to this absolute URL instead of routing traffic. */
+    redirectTo?: string | null;
 }
 interface EnvVar {
     id: number;
-    publicId: string;
     key: string;
     value: string;
+    target: EnvVarTarget;
     isSecret: boolean;
 }
 type EnvVarTarget = 'build' | 'runtime' | 'both';
@@ -284,7 +312,6 @@ interface CreateEnvVarInput {
     isSecret?: boolean;
 }
 interface UpdateEnvVarInput {
-    key?: string;
     value?: string;
     target?: EnvVarTarget;
     isSecret?: boolean;
@@ -320,11 +347,34 @@ interface MeResponse {
     };
     stripeMode?: string;
 }
-interface ServiceMetrics {
-    cpu: number;
-    memory: number;
-    network: number;
-    requests: number;
+/**
+ * A single point in a service metrics time series. Same shape used for
+ * the latest-snapshot and history endpoints.
+ */
+interface ServiceMetricsPoint {
+    timestamp: string;
+    cpuPercent: number;
+    memoryUsedMb: number;
+    memoryLimitMb: number;
+    networkRxBytes: number;
+    networkTxBytes: number;
+    diskUsedMb: number;
+}
+/**
+ * Latest-snapshot response from `services.getMetrics`. `metrics` is null
+ * before the first agent sample lands; `serverOverview` is null when the
+ * service is not currently placed on a worker (suspended, between
+ * deploys, etc).
+ */
+interface ServiceMetricsSnapshot {
+    metrics: ServiceMetricsPoint | null;
+    serverOverview: {
+        cpuPercent: number;
+        memoryUsedMb: number;
+        memoryLimitMb: number;
+        diskUsedMb: number;
+        containerCount: number;
+    } | null;
 }
 interface CronExecution {
     id: number;
@@ -369,8 +419,11 @@ declare class CronResource {
 declare class DatabasesResource {
     private client;
     constructor(client: HostStack);
-    /** List all databases for a project. */
-    list(teamId: IdInput, projectId: IdInput): Promise<{
+    /**
+     * List databases for the team. Pass `projectId` to scope to one
+     * project; omit it to list every database the team owns.
+     */
+    list(teamId: IdInput, projectId?: IdInput): Promise<{
         databases: Database[];
     }>;
     /** Get a single database by ID. */
@@ -797,10 +850,14 @@ declare class ServicesResource {
     suspend(teamId: IdInput, serviceId: IdInput): Promise<void>;
     /** Resume a suspended service. */
     resume(teamId: IdInput, serviceId: IdInput): Promise<void>;
-    /** Get service metrics. */
-    getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
-        metrics: ServiceMetrics;
-    }>;
+    /**
+     * Get the latest metrics snapshot for a service.
+     *
+     * Returns `metrics: null` before the first agent sample lands;
+     * `serverOverview: null` when the service is not currently placed
+     * (suspended, between deploys, etc).
+     */
+    getMetrics(teamId: IdInput, serviceId: IdInput): Promise<ServiceMetricsSnapshot>;
     /**
      * Get a metrics time series for a service.
      *
@@ -847,7 +904,7 @@ declare class ServicesResource {
         since?: string;
         until?: string;
         stream?: 'stdout' | 'stderr';
-        level?: 'stdout' | 'stderr' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+        level?: 'stdout' | 'stderr' | 'debug' | 'info' | 'warn' | 'error';
         search?: string;
         grep?: string;
         countOnly?: boolean;
@@ -948,10 +1005,6 @@ type ResolveScope = {
     kind: 'volume';
     teamId: number;
     serviceId: number;
-} | {
-    kind: 'envVar';
-    teamId: number;
-    serviceId: number;
 } | {
     kind: 'environment';
     teamId: number;
@@ -1009,16 +1062,29 @@ declare class HostStack {
 
 declare class HostStackError extends Error {
     readonly statusCode: number;
-    constructor(statusCode: number, message: string);
+    /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
+    readonly body: unknown;
+    constructor(statusCode: number, message: string, body?: unknown);
 }
 declare class AuthenticationError extends HostStackError {
-    constructor(message?: string);
+    constructor(message?: string, body?: unknown);
+}
+declare class ForbiddenError extends HostStackError {
+    constructor(message?: string, body?: unknown);
 }
 declare class NotFoundError extends HostStackError {
-    constructor(message?: string);
+    constructor(message?: string, body?: unknown);
+}
+declare class ConflictError extends HostStackError {
+    constructor(message?: string, body?: unknown);
 }
 declare class RateLimitError extends HostStackError {
-    constructor(message?: string);
+    /**
+     * Seconds to wait before retrying, parsed from the `Retry-After` response
+     * header. `undefined` if the server didn't send one.
+     */
+    readonly retryAfter: number | undefined;
+    constructor(message?: string, retryAfter?: number, body?: unknown);
 }
 
 /**
@@ -1051,4 +1117,4 @@ declare function buildPaginationQuery(params?: PaginationParams): string;
  */
 declare function wrapArray<T>(items: T[], params?: PaginationParams): PaginatedResponse<T>;
 
-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 };
+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.js

@@ -1,28 +1,49 @@
 // src/errors.ts
 var HostStackError = class extends Error {
   statusCode;
-  constructor(statusCode, message) {
+  /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
+  body;
+  constructor(statusCode, message, body) {
     super(message);
     this.name = "HostStackError";
     this.statusCode = statusCode;
+    this.body = body;
   }
 };
 var AuthenticationError = class extends HostStackError {
-  constructor(message = "Authentication failed. Check your API key.") {
-    super(401, message);
+  constructor(message = "Authentication failed \u2014 check your API key.", body) {
+    super(401, message, body);
     this.name = "AuthenticationError";
   }
 };
+var ForbiddenError = class extends HostStackError {
+  constructor(message = "Permission denied \u2014 API key lacks the required scope.", body) {
+    super(403, message, body);
+    this.name = "ForbiddenError";
+  }
+};
 var NotFoundError = class extends HostStackError {
-  constructor(message = "Resource not found.") {
-    super(404, message);
+  constructor(message = "Resource not found.", body) {
+    super(404, message, body);
     this.name = "NotFoundError";
   }
 };
+var ConflictError = class extends HostStackError {
+  constructor(message = "Conflict \u2014 the resource state prevents this operation.", body) {
+    super(409, message, body);
+    this.name = "ConflictError";
+  }
+};
 var RateLimitError = class extends HostStackError {
-  constructor(message = "Rate limit exceeded. Try again later.") {
-    super(429, message);
+  /**
+   * Seconds to wait before retrying, parsed from the `Retry-After` response
+   * header. `undefined` if the server didn't send one.
+   */
+  retryAfter;
+  constructor(message = "Rate limit exceeded \u2014 back off and retry.", retryAfter, body) {
+    super(429, message, body);
     this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
   }
 };
 
@@ -67,9 +88,15 @@ var DatabasesResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List all databases for a project. */
+  /**
+   * List databases for the team. Pass `projectId` to scope to one
+   * project; omit it to list every database the team owns.
+   */
   async list(teamId, projectId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
+    if (projectId === void 0) {
+      return this.client.request("GET", `/api/databases/${tid}`);
+    }
     const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
     return this.client.request("GET", `/api/databases/${tid}?projectId=${pid}`);
   }
@@ -372,22 +399,24 @@ var EnvVarsResource = class {
   async update(teamId, serviceId, envVarId, data) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
-    const eid = await this.client.resolveId(envVarId, {
-      kind: "envVar",
-      teamId: tid,
-      serviceId: sid
-    });
+    const eid = typeof envVarId === "number" ? envVarId : Number.parseInt(envVarId, 10);
+    if (Number.isNaN(eid)) {
+      throw new Error(
+        `Invalid envVarId "${envVarId}": expected a numeric id (env vars have no publicId \u2014 read it from list()).`
+      );
+    }
     return this.client.request("PATCH", `/api/services/${tid}/${sid}/env/${eid}`, data);
   }
   /** Delete an environment variable. */
   async delete(teamId, serviceId, envVarId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
-    const eid = await this.client.resolveId(envVarId, {
-      kind: "envVar",
-      teamId: tid,
-      serviceId: sid
-    });
+    const eid = typeof envVarId === "number" ? envVarId : Number.parseInt(envVarId, 10);
+    if (Number.isNaN(eid)) {
+      throw new Error(
+        `Invalid envVarId "${envVarId}": expected a numeric id (env vars have no publicId \u2014 read it from list()).`
+      );
+    }
     return this.client.request("DELETE", `/api/services/${tid}/${sid}/env/${eid}`);
   }
   /** Bulk set environment variables (create or update). */
@@ -604,7 +633,13 @@ var ServicesResource = class {
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     return this.client.request("POST", `/api/services/${tid}/${sid}/resume`);
   }
-  /** Get service metrics. */
+  /**
+   * Get the latest metrics snapshot for a service.
+   *
+   * Returns `metrics: null` before the first agent sample lands;
+   * `serverOverview: null` when the service is not currently placed
+   * (suspended, between deploys, etc).
+   */
   async getMetrics(teamId, serviceId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
@@ -748,8 +783,7 @@ var PREFIX = {
   database: "db_",
   domain: "dom_",
   volume: "vol_",
-  envVar: "env_",
-  environment: "environment_",
+  environment: "env_",
   cronExecution: "cjob_"
 };
 var HostStack = class {
@@ -820,13 +854,20 @@ var HostStack = class {
       const message = data.error ?? `HTTP ${res.status}`;
       switch (res.status) {
         case 401:
-          throw new AuthenticationError(message);
+          throw new AuthenticationError(message, data);
+        case 403:
+          throw new ForbiddenError(message, data);
         case 404:
-          throw new NotFoundError(message);
-        case 429:
-          throw new RateLimitError(message);
+          throw new NotFoundError(message, data);
+        case 409:
+          throw new ConflictError(message, data);
+        case 429: {
+          const header = res.headers.get("Retry-After");
+          const retryAfter = header && /^\d+$/.test(header) ? Number(header) : void 0;
+          throw new RateLimitError(message, retryAfter, data);
+        }
         default:
-          throw new HostStackError(res.status, message);
+          throw new HostStackError(res.status, message, data);
       }
     }
     if (res.status === 204) {
@@ -902,13 +943,6 @@ var HostStack = class {
         );
         return r.domains ?? [];
       }
-      case "envVar": {
-        const r = await this.request(
-          "GET",
-          `/api/services/${scope.teamId}/${scope.serviceId}/env`
-        );
-        return r.envVars ?? [];
-      }
       case "volume": {
         const r = await this.request("GET", `/api/services/${scope.teamId}/${scope.serviceId}/volumes`);
         return r.volumes ?? [];
@@ -941,7 +975,6 @@ function cacheScope(scope) {
       return `${scope.kind}:${scope.teamId}`;
     case "deploy":
     case "volume":
-    case "envVar":
     case "cronExecution":
       return `${scope.kind}:${scope.teamId}:${scope.serviceId}`;
   }
@@ -968,6 +1001,6 @@ function wrapArray(items, params) {
   };
 }
 
-export { AuthenticationError, HostStack, HostStackError, NotFoundError, RateLimitError, buildPaginationQuery, wrapArray };
+export { AuthenticationError, ConflictError, ForbiddenError, HostStack, HostStackError, NotFoundError, RateLimitError, buildPaginationQuery, wrapArray };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map