@hoststack.dev/sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -37,28 +37,70 @@ interface CreateServiceInput {
     buildCommand?: string;
     startCommand?: string;
 }
+/**
+ * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
+ * Nullable fields accept `null` to clear; `undefined` leaves the value unchanged.
+ */
 interface UpdateServiceInput {
     name?: string;
-}
-interface ServiceConfig {
+    branch?: string;
+    rootDirectory?: string;
+    autoDeploy?: boolean;
+    installCommand?: string | null;
     buildCommand?: string | null;
     startCommand?: string | null;
-    branch?: string | null;
-    rootDirectory?: string | null;
     dockerfilePath?: string | null;
-    autoDeploy?: boolean;
-    instanceCount?: number;
-    plan?: string;
+    healthCheckPath?: string | null;
+    cronSchedule?: string | null;
+    publishPath?: string | null;
+    runtime?: string;
 }
+interface ServiceConfig {
+    memoryMb?: number;
+    cpuShares?: number;
+    diskSizeGb?: number;
+    port?: number;
+    protocol?: 'http' | 'tcp';
+    healthCheckEnabled?: boolean;
+    healthCheckInterval?: number;
+    healthCheckTimeout?: number;
+    healthCheckGracePeriodSec?: number;
+    preDeployCommand?: string | null;
+    restartPolicy?: 'always' | 'on-failure' | 'no';
+    minInstances?: number;
+    maxInstances?: number;
+    scaleCpuThreshold?: number;
+    scaleMemoryThreshold?: number;
+    scaleRequestsPerSecThreshold?: number | null;
+    dockerImage?: string | null;
+    registryUsername?: string | null;
+    registryPassword?: string | null;
+}
+/**
+ * Fields that live on the `service_config` row — write via PATCH
+ * /services/:tid/:sid/config. Build/runtime fields (build/start command,
+ * branch, rootDirectory) belong on UpdateServiceInput, not here.
+ */
 interface UpdateServiceConfigInput {
-    buildCommand?: string;
-    startCommand?: string;
-    branch?: string;
-    rootDirectory?: string;
-    dockerfilePath?: string;
-    autoDeploy?: boolean;
-    instanceCount?: number;
-    plan?: string;
+    memoryMb?: number;
+    cpuShares?: number;
+    diskSizeGb?: number;
+    port?: number;
+    protocol?: 'http' | 'tcp';
+    healthCheckEnabled?: boolean;
+    healthCheckInterval?: number;
+    healthCheckTimeout?: number;
+    healthCheckGracePeriodSec?: number;
+    preDeployCommand?: string;
+    restartPolicy?: 'always' | 'on-failure' | 'no';
+    minInstances?: number;
+    maxInstances?: number;
+    scaleCpuThreshold?: number;
+    scaleMemoryThreshold?: number;
+    scaleRequestsPerSecThreshold?: number | null;
+    dockerImage?: string | null;
+    registryUsername?: string | null;
+    registryPassword?: string | null;
 }
 interface Deploy {
     id: number;
@@ -74,22 +116,30 @@ interface Deploy {
 interface TriggerDeployInput {
     clearCache?: boolean;
 }
+/** Managed database engines supported by HostStack. */
+type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
 interface Database {
     id: number;
     publicId: string;
     name: string;
-    type: string;
+    /** The engine name. The legacy `type` alias still ships in API responses
+     * but is deprecated — read `engine` going forward. */
+    engine: DatabaseEngine;
     status: string;
     version?: string | null;
+    plan?: string | null;
+    region?: string | null;
     projectId: number;
     createdAt: string;
     updatedAt: string;
 }
 interface CreateDatabaseInput {
     name: string;
-    type: string;
+    engine: DatabaseEngine;
     projectId: number;
     version?: string;
+    plan?: 'free' | 'starter' | 'standard' | 'pro';
+    region?: string;
 }
 interface UpdateDatabaseInput {
     name?: string;
@@ -102,6 +152,36 @@ interface DatabaseCredentials {
     database: string;
     connectionUrl: string;
 }
+/**
+ * A persistent disk attached to a service. Survives redeploys and
+ * container restarts. One service can have multiple volumes; each one is
+ * identified by a short `name` and a `mountPath` inside the container.
+ */
+interface Volume {
+    id: number;
+    publicId: string;
+    name: string;
+    mountPath: string;
+    sizeGb: number;
+    status: 'pending' | 'active' | 'deleting';
+    serviceId: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateVolumeInput {
+    /** Lowercase alphanumeric and hyphens, ≤64 chars. Used as the docker
+     *  volume identifier — change with care once data is written. */
+    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
+     *  storage quota and is metered for billing. */
+    sizeGb?: number;
+}
+interface UpdateVolumeInput {
+    mountPath?: string;
+    sizeGb?: number;
+}
 interface Domain {
     id: number;
     publicId: string;
@@ -156,8 +236,14 @@ interface Team {
     role: string;
 }
 interface MeResponse {
-    user: User;
-    team?: Team;
+    /** Null when authenticated with an API key (no associated user). */
+    user: User | null;
+    team?: Team | null;
+    apiKey?: {
+        id: number;
+        permission: string;
+    };
+    stripeMode?: string;
 }
 interface ServiceMetrics {
     cpu: number;
@@ -238,13 +324,24 @@ declare class DatabasesResource {
     resetPassword(teamId: IdInput, databaseId: IdInput): Promise<void>;
 }
 
+interface DeployListResponse {
+    data: Deploy[];
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+}
 declare class DeploysResource {
     private client;
     constructor(client: HostStack);
-    /** List deploys for a service. */
-    list(teamId: IdInput, serviceId: IdInput): Promise<{
-        deploys: Deploy[];
-    }>;
+    /**
+     * List deploys for a service. Paginated — pass `page` / `perPage` to walk
+     * pages. Default page=1, perPage=25, hard cap perPage=100.
+     */
+    list(teamId: IdInput, serviceId: IdInput, options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<DeployListResponse>;
     /** Get a single deploy by ID. */
     get(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<{
         deploy: Deploy;
@@ -257,11 +354,31 @@ declare class DeploysResource {
     cancel(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
     /** Rollback to a previous deploy. */
     rollback(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
-    /** Get build logs for a deploy. */
-    getLogs(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<{
-        logs: string;
+    /**
+     * Get build logs for a deploy.
+     *
+     * Pagination: pass `afterId` from the previous response's `nextAfterId`
+     * to fetch the next page. Per-call cap is 5000; default 500.
+     */
+    getLogs(teamId: IdInput, serviceId: IdInput, deployId: IdInput, options?: {
+        search?: string;
+        level?: string;
+        phase?: string;
+        limit?: number;
+        afterId?: number;
+    }): Promise<{
+        logs: DeployLogEntry[];
+        nextAfterId: number | null;
     }>;
 }
+interface DeployLogEntry {
+    id: number;
+    deployId: number;
+    timestamp: string;
+    level: 'info' | 'warn' | 'error' | 'debug';
+    phase: string | null;
+    message: string;
+}
 
 declare class DomainsResource {
     private client;
@@ -411,6 +528,53 @@ declare class ServicesResource {
     streamLogs(teamId: IdInput, serviceId: IdInput, options?: StreamLogsOptions): AsyncGenerator<LogEntry>;
 }
 
+/**
+ * Manage persistent disks attached to a service.
+ *
+ * Volumes mount a writable disk into a service's container at the path you
+ * choose, surviving redeploys and container restarts. One service can have
+ * multiple volumes; each one is identified by a short `name` and a
+ * `mountPath`.
+ *
+ * Renderers porting from render.yaml: a volume here is the same concept as
+ * Render's `disk:` block. Use {@link create} to attach one programmatically,
+ * or declare it in `hoststack.yaml` for IaC workflows.
+ *
+ * @example
+ * ```ts
+ * await client.volumes.create(team, service, {
+ *   name: 'data',
+ *   mountPath: '/var/data',
+ *   sizeGb: 10,
+ * });
+ * ```
+ */
+declare class VolumesResource {
+    private client;
+    constructor(client: HostStack);
+    /** List volumes attached to a service. */
+    list(teamId: IdInput, serviceId: IdInput): Promise<{
+        volumes: Volume[];
+    }>;
+    /** Attach a new volume to a service. Triggers provisioning on the host. */
+    create(teamId: IdInput, serviceId: IdInput, data: CreateVolumeInput): Promise<{
+        volume: Volume;
+    }>;
+    /**
+     * Update a volume's mountPath or sizeGb. Resizes that take effect on the
+     * next deploy; mountPath changes require a redeploy to remount.
+     */
+    update(teamId: IdInput, serviceId: IdInput, volumeId: IdInput, data: UpdateVolumeInput): Promise<{
+        volume: Volume;
+    }>;
+    /**
+     * Detach and deprovision a volume. The underlying disk is destroyed —
+     * back up any data first. Async: the row is marked `deleting` and the
+     * agent finalises the removal once it acks.
+     */
+    delete(teamId: IdInput, serviceId: IdInput, volumeId: IdInput): Promise<void>;
+}
+
 /** A numeric id or a publicId string (e.g. 42, "42", "svc_abc…"). */
 type IdInput = number | string;
 interface HostStackOptions {
@@ -437,6 +601,10 @@ type ResolveScope = {
 } | {
     kind: 'domain';
     teamId: number;
+} | {
+    kind: 'volume';
+    teamId: number;
+    serviceId: number;
 } | {
     kind: 'envVar';
     teamId: number;
@@ -464,6 +632,8 @@ declare class HostStack {
     readonly envVars: EnvVarsResource;
     /** Manage cron job executions. */
     readonly cron: CronResource;
+    /** Manage persistent disks attached to services. */
+    readonly volumes: VolumesResource;
     constructor(options: HostStackOptions);
     /**
      * Make an authenticated request to the HostStack API.

package/dist/index.d.ts

@@ -37,28 +37,70 @@ interface CreateServiceInput {
     buildCommand?: string;
     startCommand?: string;
 }
+/**
+ * Fields that live on the `services` row — write via PATCH /services/:tid/:sid.
+ * Nullable fields accept `null` to clear; `undefined` leaves the value unchanged.
+ */
 interface UpdateServiceInput {
     name?: string;
-}
-interface ServiceConfig {
+    branch?: string;
+    rootDirectory?: string;
+    autoDeploy?: boolean;
+    installCommand?: string | null;
     buildCommand?: string | null;
     startCommand?: string | null;
-    branch?: string | null;
-    rootDirectory?: string | null;
     dockerfilePath?: string | null;
-    autoDeploy?: boolean;
-    instanceCount?: number;
-    plan?: string;
+    healthCheckPath?: string | null;
+    cronSchedule?: string | null;
+    publishPath?: string | null;
+    runtime?: string;
 }
+interface ServiceConfig {
+    memoryMb?: number;
+    cpuShares?: number;
+    diskSizeGb?: number;
+    port?: number;
+    protocol?: 'http' | 'tcp';
+    healthCheckEnabled?: boolean;
+    healthCheckInterval?: number;
+    healthCheckTimeout?: number;
+    healthCheckGracePeriodSec?: number;
+    preDeployCommand?: string | null;
+    restartPolicy?: 'always' | 'on-failure' | 'no';
+    minInstances?: number;
+    maxInstances?: number;
+    scaleCpuThreshold?: number;
+    scaleMemoryThreshold?: number;
+    scaleRequestsPerSecThreshold?: number | null;
+    dockerImage?: string | null;
+    registryUsername?: string | null;
+    registryPassword?: string | null;
+}
+/**
+ * Fields that live on the `service_config` row — write via PATCH
+ * /services/:tid/:sid/config. Build/runtime fields (build/start command,
+ * branch, rootDirectory) belong on UpdateServiceInput, not here.
+ */
 interface UpdateServiceConfigInput {
-    buildCommand?: string;
-    startCommand?: string;
-    branch?: string;
-    rootDirectory?: string;
-    dockerfilePath?: string;
-    autoDeploy?: boolean;
-    instanceCount?: number;
-    plan?: string;
+    memoryMb?: number;
+    cpuShares?: number;
+    diskSizeGb?: number;
+    port?: number;
+    protocol?: 'http' | 'tcp';
+    healthCheckEnabled?: boolean;
+    healthCheckInterval?: number;
+    healthCheckTimeout?: number;
+    healthCheckGracePeriodSec?: number;
+    preDeployCommand?: string;
+    restartPolicy?: 'always' | 'on-failure' | 'no';
+    minInstances?: number;
+    maxInstances?: number;
+    scaleCpuThreshold?: number;
+    scaleMemoryThreshold?: number;
+    scaleRequestsPerSecThreshold?: number | null;
+    dockerImage?: string | null;
+    registryUsername?: string | null;
+    registryPassword?: string | null;
 }
 interface Deploy {
     id: number;
@@ -74,22 +116,30 @@ interface Deploy {
 interface TriggerDeployInput {
     clearCache?: boolean;
 }
+/** Managed database engines supported by HostStack. */
+type DatabaseEngine = 'postgres' | 'redis' | 'mysql' | 'mariadb' | 'mongodb';
 interface Database {
     id: number;
     publicId: string;
     name: string;
-    type: string;
+    /** The engine name. The legacy `type` alias still ships in API responses
+     * but is deprecated — read `engine` going forward. */
+    engine: DatabaseEngine;
     status: string;
     version?: string | null;
+    plan?: string | null;
+    region?: string | null;
     projectId: number;
     createdAt: string;
     updatedAt: string;
 }
 interface CreateDatabaseInput {
     name: string;
-    type: string;
+    engine: DatabaseEngine;
     projectId: number;
     version?: string;
+    plan?: 'free' | 'starter' | 'standard' | 'pro';
+    region?: string;
 }
 interface UpdateDatabaseInput {
     name?: string;
@@ -102,6 +152,36 @@ interface DatabaseCredentials {
     database: string;
     connectionUrl: string;
 }
+/**
+ * A persistent disk attached to a service. Survives redeploys and
+ * container restarts. One service can have multiple volumes; each one is
+ * identified by a short `name` and a `mountPath` inside the container.
+ */
+interface Volume {
+    id: number;
+    publicId: string;
+    name: string;
+    mountPath: string;
+    sizeGb: number;
+    status: 'pending' | 'active' | 'deleting';
+    serviceId: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateVolumeInput {
+    /** Lowercase alphanumeric and hyphens, ≤64 chars. Used as the docker
+     *  volume identifier — change with care once data is written. */
+    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
+     *  storage quota and is metered for billing. */
+    sizeGb?: number;
+}
+interface UpdateVolumeInput {
+    mountPath?: string;
+    sizeGb?: number;
+}
 interface Domain {
     id: number;
     publicId: string;
@@ -156,8 +236,14 @@ interface Team {
     role: string;
 }
 interface MeResponse {
-    user: User;
-    team?: Team;
+    /** Null when authenticated with an API key (no associated user). */
+    user: User | null;
+    team?: Team | null;
+    apiKey?: {
+        id: number;
+        permission: string;
+    };
+    stripeMode?: string;
 }
 interface ServiceMetrics {
     cpu: number;
@@ -238,13 +324,24 @@ declare class DatabasesResource {
     resetPassword(teamId: IdInput, databaseId: IdInput): Promise<void>;
 }
 
+interface DeployListResponse {
+    data: Deploy[];
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+}
 declare class DeploysResource {
     private client;
     constructor(client: HostStack);
-    /** List deploys for a service. */
-    list(teamId: IdInput, serviceId: IdInput): Promise<{
-        deploys: Deploy[];
-    }>;
+    /**
+     * List deploys for a service. Paginated — pass `page` / `perPage` to walk
+     * pages. Default page=1, perPage=25, hard cap perPage=100.
+     */
+    list(teamId: IdInput, serviceId: IdInput, options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<DeployListResponse>;
     /** Get a single deploy by ID. */
     get(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<{
         deploy: Deploy;
@@ -257,11 +354,31 @@ declare class DeploysResource {
     cancel(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
     /** Rollback to a previous deploy. */
     rollback(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
-    /** Get build logs for a deploy. */
-    getLogs(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<{
-        logs: string;
+    /**
+     * Get build logs for a deploy.
+     *
+     * Pagination: pass `afterId` from the previous response's `nextAfterId`
+     * to fetch the next page. Per-call cap is 5000; default 500.
+     */
+    getLogs(teamId: IdInput, serviceId: IdInput, deployId: IdInput, options?: {
+        search?: string;
+        level?: string;
+        phase?: string;
+        limit?: number;
+        afterId?: number;
+    }): Promise<{
+        logs: DeployLogEntry[];
+        nextAfterId: number | null;
     }>;
 }
+interface DeployLogEntry {
+    id: number;
+    deployId: number;
+    timestamp: string;
+    level: 'info' | 'warn' | 'error' | 'debug';
+    phase: string | null;
+    message: string;
+}
 
 declare class DomainsResource {
     private client;
@@ -411,6 +528,53 @@ declare class ServicesResource {
     streamLogs(teamId: IdInput, serviceId: IdInput, options?: StreamLogsOptions): AsyncGenerator<LogEntry>;
 }
 
+/**
+ * Manage persistent disks attached to a service.
+ *
+ * Volumes mount a writable disk into a service's container at the path you
+ * choose, surviving redeploys and container restarts. One service can have
+ * multiple volumes; each one is identified by a short `name` and a
+ * `mountPath`.
+ *
+ * Renderers porting from render.yaml: a volume here is the same concept as
+ * Render's `disk:` block. Use {@link create} to attach one programmatically,
+ * or declare it in `hoststack.yaml` for IaC workflows.
+ *
+ * @example
+ * ```ts
+ * await client.volumes.create(team, service, {
+ *   name: 'data',
+ *   mountPath: '/var/data',
+ *   sizeGb: 10,
+ * });
+ * ```
+ */
+declare class VolumesResource {
+    private client;
+    constructor(client: HostStack);
+    /** List volumes attached to a service. */
+    list(teamId: IdInput, serviceId: IdInput): Promise<{
+        volumes: Volume[];
+    }>;
+    /** Attach a new volume to a service. Triggers provisioning on the host. */
+    create(teamId: IdInput, serviceId: IdInput, data: CreateVolumeInput): Promise<{
+        volume: Volume;
+    }>;
+    /**
+     * Update a volume's mountPath or sizeGb. Resizes that take effect on the
+     * next deploy; mountPath changes require a redeploy to remount.
+     */
+    update(teamId: IdInput, serviceId: IdInput, volumeId: IdInput, data: UpdateVolumeInput): Promise<{
+        volume: Volume;
+    }>;
+    /**
+     * Detach and deprovision a volume. The underlying disk is destroyed —
+     * back up any data first. Async: the row is marked `deleting` and the
+     * agent finalises the removal once it acks.
+     */
+    delete(teamId: IdInput, serviceId: IdInput, volumeId: IdInput): Promise<void>;
+}
+
 /** A numeric id or a publicId string (e.g. 42, "42", "svc_abc…"). */
 type IdInput = number | string;
 interface HostStackOptions {
@@ -437,6 +601,10 @@ type ResolveScope = {
 } | {
     kind: 'domain';
     teamId: number;
+} | {
+    kind: 'volume';
+    teamId: number;
+    serviceId: number;
 } | {
     kind: 'envVar';
     teamId: number;
@@ -464,6 +632,8 @@ declare class HostStack {
     readonly envVars: EnvVarsResource;
     /** Manage cron job executions. */
     readonly cron: CronResource;
+    /** Manage persistent disks attached to services. */
+    readonly volumes: VolumesResource;
     constructor(options: HostStackOptions);
     /**
      * Make an authenticated request to the HostStack API.