@hoststack.dev/sdk 0.1.1 → 0.2.1

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;
@@ -104,7 +154,7 @@ interface DatabaseCredentials {
 }
 interface Domain {
     id: number;
-    publicId?: string;
+    publicId: string;
     domain: string;
     status: string;
     verified: boolean;
@@ -120,7 +170,7 @@ interface UpdateDomainInput {
 }
 interface EnvVar {
     id: number;
-    publicId?: string;
+    publicId: string;
     key: string;
     value: string;
     isSecret: boolean;
@@ -150,13 +200,20 @@ interface User {
 }
 interface Team {
     id: number;
+    publicId: string;
     name: string;
     slug: string;
     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;
@@ -189,17 +246,17 @@ declare class CronResource {
     private client;
     constructor(client: HostStack);
     /** List cron executions for a service. */
-    list(teamId: number, serviceId: string, options?: {
+    list(teamId: IdInput, serviceId: IdInput, options?: {
         limit?: number;
     }): Promise<{
         executions: CronExecution[];
     }>;
     /** Get a single cron execution by ID. */
-    get(teamId: number, serviceId: string, executionId: string): Promise<{
+    get(teamId: IdInput, serviceId: IdInput, executionId: IdInput): Promise<{
         execution: CronExecution;
     }>;
     /** Trigger an immediate cron execution. */
-    trigger(teamId: number, serviceId: string): Promise<{
+    trigger(teamId: IdInput, serviceId: IdInput): Promise<{
         execution: CronExecution;
     }>;
 }
@@ -208,123 +265,154 @@ declare class DatabasesResource {
     private client;
     constructor(client: HostStack);
     /** List all databases for a project. */
-    list(teamId: number, projectId: number): Promise<{
+    list(teamId: IdInput, projectId: IdInput): Promise<{
         databases: Database[];
     }>;
     /** Get a single database by ID. */
-    get(teamId: number, databaseId: string): Promise<{
+    get(teamId: IdInput, databaseId: IdInput): Promise<{
         database: Database;
     }>;
     /** Create a new database. */
-    create(teamId: number, data: CreateDatabaseInput): Promise<{
+    create(teamId: IdInput, data: CreateDatabaseInput): Promise<{
         database: Database;
     }>;
     /** Update a database. */
-    update(teamId: number, databaseId: string, data: UpdateDatabaseInput): Promise<{
+    update(teamId: IdInput, databaseId: IdInput, data: UpdateDatabaseInput): Promise<{
         database: Database;
     }>;
     /** Delete a database. */
-    delete(teamId: number, databaseId: string): Promise<void>;
+    delete(teamId: IdInput, databaseId: IdInput): Promise<void>;
     /** Suspend a database. */
-    suspend(teamId: number, databaseId: string): Promise<void>;
+    suspend(teamId: IdInput, databaseId: IdInput): Promise<void>;
     /** Resume a suspended database. */
-    resume(teamId: number, databaseId: string): Promise<void>;
+    resume(teamId: IdInput, databaseId: IdInput): Promise<void>;
     /** Get connection credentials. */
-    getCredentials(teamId: number, databaseId: string): Promise<{
+    getCredentials(teamId: IdInput, databaseId: IdInput): Promise<{
         credentials: DatabaseCredentials;
     }>;
     /** Reset the database password. */
-    resetPassword(teamId: number, databaseId: string): Promise<void>;
+    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: number, serviceId: string): 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: number, serviceId: string, deployId: string): Promise<{
+    get(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<{
         deploy: Deploy;
     }>;
     /** Trigger a new deploy. */
-    trigger(teamId: number, serviceId: string, data?: TriggerDeployInput): Promise<{
+    trigger(teamId: IdInput, serviceId: IdInput, data?: TriggerDeployInput): Promise<{
         deploy: Deploy;
     }>;
     /** Cancel an in-progress deploy. */
-    cancel(teamId: number, serviceId: string, deployId: string): Promise<void>;
+    cancel(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
     /** Rollback to a previous deploy. */
-    rollback(teamId: number, serviceId: string, deployId: string): Promise<void>;
-    /** Get build logs for a deploy. */
-    getLogs(teamId: number, serviceId: string, deployId: string): Promise<{
-        logs: string;
+    rollback(teamId: IdInput, serviceId: IdInput, deployId: IdInput): Promise<void>;
+    /**
+     * 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;
     constructor(client: HostStack);
     /** List all domains for the active team. */
-    list(teamId: number): Promise<{
+    list(teamId: IdInput): Promise<{
         domains: Domain[];
     }>;
     /** Add a custom domain. */
-    add(teamId: number, data: AddDomainInput): Promise<{
+    add(teamId: IdInput, data: AddDomainInput): Promise<{
         domain: Domain;
     }>;
     /** Update a domain. */
-    update(teamId: number, domainId: string, data: UpdateDomainInput): Promise<{
+    update(teamId: IdInput, domainId: IdInput, data: UpdateDomainInput): Promise<{
         domain: Domain;
     }>;
     /** Remove a domain. */
-    remove(teamId: number, domainId: string): Promise<void>;
+    remove(teamId: IdInput, domainId: IdInput): Promise<void>;
     /** Verify domain DNS configuration. */
-    verify(teamId: number, domainId: string): Promise<void>;
+    verify(teamId: IdInput, domainId: IdInput): Promise<void>;
 }
 
 declare class EnvVarsResource {
     private client;
     constructor(client: HostStack);
     /** List all environment variables for a service. */
-    list(teamId: number, serviceId: string): Promise<{
+    list(teamId: IdInput, serviceId: IdInput): Promise<{
         envVars: EnvVar[];
     }>;
     /** Create a new environment variable. */
-    create(teamId: number, serviceId: string, data: CreateEnvVarInput): Promise<{
+    create(teamId: IdInput, serviceId: IdInput, data: CreateEnvVarInput): Promise<{
         envVar: EnvVar;
     }>;
     /** Update an environment variable. */
-    update(teamId: number, serviceId: string, envVarId: string, data: UpdateEnvVarInput): Promise<{
+    update(teamId: IdInput, serviceId: IdInput, envVarId: IdInput, data: UpdateEnvVarInput): Promise<{
         envVar: EnvVar;
     }>;
     /** Delete an environment variable. */
-    delete(teamId: number, serviceId: string, envVarId: string): Promise<void>;
+    delete(teamId: IdInput, serviceId: IdInput, envVarId: IdInput): Promise<void>;
     /** Bulk set environment variables (create or update). */
-    bulkSet(teamId: number, serviceId: string, data: BulkSetEnvVarsInput): Promise<void>;
+    bulkSet(teamId: IdInput, serviceId: IdInput, data: BulkSetEnvVarsInput): Promise<void>;
 }
 
 declare class ProjectsResource {
     private client;
     constructor(client: HostStack);
     /** List all projects for the active team. */
-    list(teamId: number): Promise<{
+    list(teamId: IdInput): Promise<{
         projects: Project[];
     }>;
     /** Get a single project by ID. */
-    get(teamId: number, projectId: string): Promise<{
+    get(teamId: IdInput, projectId: IdInput): Promise<{
         project: Project;
     }>;
     /** Create a new project. */
-    create(teamId: number, data: CreateProjectInput): Promise<{
+    create(teamId: IdInput, data: CreateProjectInput): Promise<{
         project: Project;
     }>;
     /** Update a project. */
-    update(teamId: number, projectId: string, data: UpdateProjectInput): Promise<{
+    update(teamId: IdInput, projectId: IdInput, data: UpdateProjectInput): Promise<{
         project: Project;
     }>;
     /** Delete a project. */
-    delete(teamId: number, projectId: string): Promise<void>;
+    delete(teamId: IdInput, projectId: IdInput): Promise<void>;
 }
 
 interface LogEntry$1 {
@@ -354,41 +442,41 @@ declare class ServicesResource {
     private client;
     constructor(client: HostStack);
     /** List all services for the active team. */
-    list(teamId: number): Promise<{
+    list(teamId: IdInput): Promise<{
         services: Service[];
     }>;
     /** Get a single service by ID. */
-    get(teamId: number, serviceId: string): Promise<{
+    get(teamId: IdInput, serviceId: IdInput): Promise<{
         service: Service;
     }>;
     /** Create a new service. */
-    create(teamId: number, data: CreateServiceInput): Promise<{
+    create(teamId: IdInput, data: CreateServiceInput): Promise<{
         service: Service;
     }>;
     /** Update a service. */
-    update(teamId: number, serviceId: string, data: UpdateServiceInput): Promise<{
+    update(teamId: IdInput, serviceId: IdInput, data: UpdateServiceInput): Promise<{
         service: Service;
     }>;
     /** Delete a service. */
-    delete(teamId: number, serviceId: string): Promise<void>;
+    delete(teamId: IdInput, serviceId: IdInput): Promise<void>;
     /** Suspend a service. */
-    suspend(teamId: number, serviceId: string): Promise<void>;
+    suspend(teamId: IdInput, serviceId: IdInput): Promise<void>;
     /** Resume a suspended service. */
-    resume(teamId: number, serviceId: string): Promise<void>;
+    resume(teamId: IdInput, serviceId: IdInput): Promise<void>;
     /** Get service metrics. */
-    getMetrics(teamId: number, serviceId: string): Promise<{
+    getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
         metrics: ServiceMetrics;
     }>;
     /** Get service configuration. */
-    getConfig(teamId: number, serviceId: string): Promise<{
+    getConfig(teamId: IdInput, serviceId: IdInput): Promise<{
         config: ServiceConfig;
     }>;
     /** Update service configuration. */
-    updateConfig(teamId: number, serviceId: string, data: UpdateServiceConfigInput): Promise<{
+    updateConfig(teamId: IdInput, serviceId: IdInput, data: UpdateServiceConfigInput): Promise<{
         config: ServiceConfig;
     }>;
     /** Get runtime logs for a service. */
-    getRuntimeLogs(teamId: number, serviceId: string, options?: {
+    getRuntimeLogs(teamId: IdInput, serviceId: IdInput, options?: {
         lines?: number;
         since?: string;
         stream?: 'stdout' | 'stderr';
@@ -407,18 +495,48 @@ declare class ServicesResource {
      * }
      * ```
      */
-    streamLogs(teamId: number, serviceId: string, options?: StreamLogsOptions): AsyncGenerator<LogEntry>;
+    streamLogs(teamId: IdInput, serviceId: IdInput, options?: StreamLogsOptions): AsyncGenerator<LogEntry>;
 }
 
+/** A numeric id or a publicId string (e.g. 42, "42", "svc_abc…"). */
+type IdInput = number | string;
 interface HostStackOptions {
     /** Your HostStack API key (hs_live_... or hs_test_...). */
     apiKey: string;
     /** Base URL of the HostStack API. Defaults to https://hoststack.dev */
     baseUrl?: string;
 }
+type ResolveScope = {
+    kind: 'team';
+} | {
+    kind: 'project';
+    teamId: number;
+} | {
+    kind: 'service';
+    teamId: number;
+} | {
+    kind: 'deploy';
+    teamId: number;
+    serviceId: number;
+} | {
+    kind: 'database';
+    teamId: number;
+} | {
+    kind: 'domain';
+    teamId: number;
+} | {
+    kind: 'envVar';
+    teamId: number;
+    serviceId: number;
+} | {
+    kind: 'cronExecution';
+    teamId: number;
+    serviceId: number;
+};
 declare class HostStack {
     private apiKey;
     private baseUrl;
+    private idCache;
     /** Manage projects. */
     readonly projects: ProjectsResource;
     /** Manage services (web, worker, cron). */
@@ -439,6 +557,17 @@ declare class HostStack {
      * Used internally by resource classes. Can also be used for custom API calls.
      */
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Resolve a publicId-or-numeric id input to a numeric database id. Numeric
+     * inputs short-circuit; publicIds (svc_xyz, dpl_xyz, etc.) are looked up
+     * via the relevant list endpoint and cached on this client instance.
+     *
+     * The API addresses everything by numeric id internally; this resolver lets
+     * SDK/MCP consumers pass either form interchangeably without burning extra
+     * round-trips on subsequent calls.
+     */
+    resolveId(input: IdInput, scope: ResolveScope): Promise<number>;
+    private fetchForResolution;
 }
 
 declare class HostStackError extends Error {