@hoststack.dev/sdk 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -32,6 +32,12 @@ interface CreateServiceInput {
     name: string;
     type: string;
     projectId?: string;
+    /**
+     * 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;
     branch?: string;
     buildCommand?: string;
@@ -75,6 +81,15 @@ interface ServiceConfig {
     dockerImage?: string | null;
     registryUsername?: string | null;
     registryPassword?: string | null;
+    /**
+     * v72.2: applied to runtime logs at query time. Reflects what the
+     * service is currently configured to filter; null/absent means no
+     * filtering. See UpdateServiceConfigInput for the write side.
+     */
+    logFilterRules?: Array<{
+        pattern: string;
+        action: 'drop' | 'downgrade';
+    }> | null;
 }
 /**
  * Fields that live on the `service_config` row — write via PATCH
@@ -101,6 +116,18 @@ interface UpdateServiceConfigInput {
     dockerImage?: string | null;
     registryUsername?: string | null;
     registryPassword?: string | null;
+    /**
+     * v72.2: per-service runtime-log filter rules applied at query
+     * time. Each rule matches the message by case-insensitive
+     * substring; matching rows are either dropped or have their
+     * stream flipped from stderr → stdout. Pass an empty array to
+     * clear all rules; null/omitted leaves the existing rules in
+     * place. Capped at 50 rules.
+     */
+    logFilterRules?: Array<{
+        pattern: string;
+        action: 'drop' | 'downgrade';
+    }> | null;
 }
 interface Deploy {
     id: number;
@@ -112,6 +139,19 @@ interface Deploy {
     createdAt: string;
     startedAt?: string | null;
     finishedAt?: string | null;
+    /**
+     * Wall-clock for the docker build / image-pull step only.
+     * Null when the deploy didn't reach the build phase (cancelled
+     * pre-pickup) or used a pre-built image with no measured pull.
+     */
+    buildDurationMs?: number | null;
+    /**
+     * Wall-clock for the full deploy pipeline (build + container
+     * start + health-check + traffic switch + cleanup), computed at
+     * serialize time from finishedAt − startedAt. Absent for deploys
+     * still in-flight or that never reached `startedAt`.
+     */
+    totalDurationMs?: number;
 }
 interface TriggerDeployInput {
     clearCache?: boolean;
@@ -130,6 +170,8 @@ interface Database {
     plan?: string | null;
     region?: string | null;
     projectId: number;
+    diskSizeGb?: number;
+    memoryMb?: number;
     createdAt: string;
     updatedAt: string;
 }
@@ -137,12 +179,20 @@ interface CreateDatabaseInput {
     name: string;
     engine: DatabaseEngine;
     projectId: number;
+    /**
+     * v66 P5: bind the new database to a specific environment in the
+     * project. Omit to default to the project's Production env.
+     */
+    environmentId?: number;
     version?: string;
     plan?: 'free' | 'starter' | 'standard' | 'pro';
     region?: string;
 }
 interface UpdateDatabaseInput {
     name?: string;
+    plan?: 'free' | 'starter' | 'standard' | 'pro';
+    /** Grow the database disk in GB. Cannot shrink. */
+    diskSizeGb?: number;
 }
 interface DatabaseCredentials {
     host: string;
@@ -205,20 +255,24 @@ interface EnvVar {
     value: string;
     isSecret: boolean;
 }
+type EnvVarTarget = 'build' | 'runtime' | 'both';
 interface CreateEnvVarInput {
     key: string;
     value: string;
+    target?: EnvVarTarget;
     isSecret?: boolean;
 }
 interface UpdateEnvVarInput {
     key?: string;
     value?: string;
+    target?: EnvVarTarget;
     isSecret?: boolean;
 }
 interface BulkSetEnvVarsInput {
-    envVars: Array<{
+    vars: Array<{
         key: string;
         value: string;
+        target?: EnvVarTarget;
         isSecret?: boolean;
     }>;
 }
@@ -354,6 +408,15 @@ 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>;
+    /**
+     * v66 P5: promote a built deploy to a sibling service in another
+     * environment. Reuses the source deploy's docker image (no rebuild).
+     * If no sibling service exists in the target env yet, the API auto-
+     * creates one by cloning the source service's config.
+     */
+    promote(teamId: IdInput, serviceId: IdInput, deployId: IdInput, targetEnvironmentId: number): Promise<{
+        deploy: Deploy;
+    }>;
     /**
      * Get build logs for a deploy.
      *
@@ -401,6 +464,76 @@ declare class DomainsResource {
     verify(teamId: IdInput, domainId: IdInput): Promise<void>;
 }
 
+interface Environment {
+    id: number;
+    publicId: string;
+    projectId: number;
+    name: string;
+    type: 'production' | 'staging' | 'development' | 'preview';
+    isDefault: boolean;
+    isProtected: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateEnvironmentInput {
+    name: string;
+    type: 'production' | 'staging' | 'development' | 'preview';
+    isProtected?: boolean;
+}
+interface UpdateEnvironmentInput {
+    name?: string;
+    isDefault?: boolean;
+    isProtected?: boolean;
+}
+/**
+ * v66 P5: programmatic env management. Each project has at least a
+ * Production env auto-created at project creation; you can add more
+ * via `create` and bind services/databases to them via the
+ * `environmentId` field on those resources' create inputs.
+ *
+ * @example
+ * ```ts
+ * const { environment: staging } = await client.environments.create(
+ *   teamId,
+ *   projectId,
+ *   { name: 'Staging', type: 'staging' }
+ * );
+ * await client.services.create(teamId, {
+ *   projectId,
+ *   environmentId: staging.id,
+ *   name: 'api',
+ *   type: 'web_service',
+ *   // ...
+ * });
+ * ```
+ */
+declare class EnvironmentsResource {
+    private client;
+    constructor(client: HostStack);
+    /** List all environments for a project. */
+    list(teamId: IdInput, projectId: IdInput): Promise<{
+        environments: Environment[];
+    }>;
+    /** Get a single environment by id. */
+    get(teamId: IdInput, projectId: IdInput, envId: IdInput): Promise<{
+        environment: Environment;
+    }>;
+    /** Create a new environment in the given project. */
+    create(teamId: IdInput, projectId: IdInput, data: CreateEnvironmentInput): Promise<{
+        environment: Environment;
+    }>;
+    /** Update environment metadata (name, default flag, protected flag). */
+    update(teamId: IdInput, projectId: IdInput, envId: IdInput, data: UpdateEnvironmentInput): Promise<{
+        environment: Environment;
+    }>;
+    /**
+     * Delete an environment. The API blocks delete when the env still
+     * has services or databases attached — destroy them first or move
+     * them to another env. Cannot delete the project's default env.
+     */
+    delete(teamId: IdInput, projectId: IdInput, envId: IdInput): Promise<void>;
+}
+
 declare class EnvVarsResource {
     private client;
     constructor(client: HostStack);
@@ -422,6 +555,81 @@ declare class EnvVarsResource {
     bulkSet(teamId: IdInput, serviceId: IdInput, data: BulkSetEnvVarsInput): Promise<void>;
 }
 
+type NotificationChannelType = 'slack' | 'discord' | 'email';
+/**
+ * Events a notification channel can subscribe to. Source of truth is
+ * `packages/shared/src/schemas/notification-channel.ts:NOTIFICATION_CHANNEL_EVENTS`.
+ */
+type NotificationChannelEvent = 'deploy.started' | 'deploy.succeeded' | 'deploy.failed' | 'deploy.failed_consecutive' | 'service.created' | 'service.deleted' | 'service.suspended' | 'service.resumed' | 'service.restart_failed' | 'service.auto_suspended' | 'service.acme_cert_failed' | 'git.auth_failed';
+interface NotificationChannel {
+    id: number;
+    teamId: number;
+    type: NotificationChannelType;
+    name: string;
+    /**
+     * Webhook URL (Slack/Discord) or email address. The list API masks
+     * the value for security — only the create/update calls round-trip
+     * the real URL.
+     */
+    webhookUrl: string;
+    active: boolean;
+    events: NotificationChannelEvent[];
+    createdAt: string;
+    updatedAt: string;
+}
+declare class NotificationsResource {
+    private client;
+    constructor(client: HostStack);
+    /**
+     * List notification channels for the team. Webhook URLs are
+     * server-side masked in the response so this is safe to log.
+     */
+    listChannels(teamId: IdInput): Promise<{
+        channels: NotificationChannel[];
+    }>;
+    /**
+     * Create a Slack/Discord/email notification channel.
+     *
+     * For type=email, `webhookUrl` is the recipient email address; for
+     * type=slack/discord it's the incoming webhook URL.
+     *
+     * `events` is the explicit subscription list — an empty array means
+     * "receive nothing". The platform pre-selects the critical-event
+     * set on the dashboard, but SDK callers must pass the list
+     * explicitly so behaviour is deterministic.
+     */
+    createChannel(teamId: IdInput, data: {
+        type: NotificationChannelType;
+        name: string;
+        webhookUrl: string;
+        events: NotificationChannelEvent[];
+    }): Promise<{
+        channel: NotificationChannel;
+    }>;
+    /**
+     * Update a channel's name / active state / event subscriptions. The
+     * webhook URL and type are immutable — create a new channel if
+     * those need to change.
+     */
+    updateChannel(teamId: IdInput, channelId: number, data: {
+        name?: string;
+        active?: boolean;
+        events?: NotificationChannelEvent[];
+    }): Promise<{
+        channel: NotificationChannel;
+    }>;
+    /** Delete a notification channel. */
+    deleteChannel(teamId: IdInput, channelId: number): Promise<void>;
+    /**
+     * Fire a test event to the channel so the user can confirm the
+     * webhook is wired correctly. Returns the dispatch outcome.
+     */
+    testChannel(teamId: IdInput, channelId: number): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+
 declare class ProjectsResource {
     private client;
     constructor(client: HostStack);
@@ -447,8 +655,13 @@ declare class ProjectsResource {
 
 interface LogEntry$1 {
     timestamp: string;
-    level?: string | null;
-    stream?: string | null;
+    /**
+     * Parsed log level if the message is a structured JSON envelope
+     * (pino numeric, `{"level":"info"}`, or `{"severity":"WARNING"}`).
+     * `undefined` for plain-text logs.
+     */
+    level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | null;
+    stream?: 'stdout' | 'stderr' | null;
     message: string;
 }
 interface StreamLogsOptions {
@@ -464,15 +677,30 @@ interface StreamLogsOptions {
 
 interface LogEntry {
     timestamp: string;
-    level?: string | null;
-    stream?: string | null;
+    /**
+     * Parsed structured log level (pino numeric or string envelopes).
+     * `undefined` for plain-text logs.
+     */
+    level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | null;
+    stream?: 'stdout' | 'stderr' | null;
     message: string;
 }
 declare class ServicesResource {
     private client;
     constructor(client: HostStack);
-    /** List all services for the active team. */
-    list(teamId: IdInput): Promise<{
+    /**
+     * List services for the active team.
+     *
+     * Optional filters narrow by project, environment, status, or type.
+     * The server treats unknown enum values as no match (returns empty)
+     * rather than 400-ing.
+     */
+    list(teamId: IdInput, filters?: {
+        projectId?: number | string;
+        environmentId?: number | string;
+        status?: 'active' | 'deploying' | 'suspended' | 'failed' | 'not_deployed';
+        type?: 'web_service' | 'private_service' | 'worker' | 'cron_job' | 'static_site';
+    }): Promise<{
         services: Service[];
     }>;
     /** Get a single service by ID. */
@@ -497,6 +725,27 @@ declare class ServicesResource {
     getMetrics(teamId: IdInput, serviceId: IdInput): Promise<{
         metrics: ServiceMetrics;
     }>;
+    /**
+     * Get a metrics time series for a service.
+     *
+     * `from`/`to` accept ISO-8601 timestamps. Omit both for the trailing
+     * hour. Server picks the resolution: raw samples ≤7d, hourly pre-
+     * aggregates ≤30d, daily beyond that. Up to ~500 points returned.
+     */
+    getMetricsHistory(teamId: IdInput, serviceId: IdInput, options?: {
+        from?: string;
+        to?: string;
+    }): Promise<{
+        history: Array<{
+            timestamp: string;
+            cpuPercent: number;
+            memoryUsedMb: number;
+            memoryLimitMb: number;
+            networkRxBytes: number;
+            networkTxBytes: number;
+            diskUsedMb: number;
+        }>;
+    }>;
     /** Get service configuration. */
     getConfig(teamId: IdInput, serviceId: IdInput): Promise<{
         config: ServiceConfig;
@@ -505,13 +754,31 @@ declare class ServicesResource {
     updateConfig(teamId: IdInput, serviceId: IdInput, data: UpdateServiceConfigInput): Promise<{
         config: ServiceConfig;
     }>;
-    /** Get runtime logs for a service. */
+    /**
+     * Get runtime logs for a service.
+     *
+     * `since`/`until` accept either an ISO-8601 timestamp or a short
+     * relative offset like `-5m`, `-1h`, `-2d`.
+     *
+     * `search` does case-insensitive substring filtering server-side
+     * (≤100 chars). `countOnly` returns just `{ count: N }` for cheap
+     * polling — useful when you want to know "how many error lines in the
+     * last 5 minutes" without paying the bytes.
+     */
     getRuntimeLogs(teamId: IdInput, serviceId: IdInput, options?: {
         lines?: number;
+        limit?: number;
         since?: string;
+        until?: string;
         stream?: 'stdout' | 'stderr';
+        level?: 'stdout' | 'stderr' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+        search?: string;
+        grep?: string;
+        countOnly?: boolean;
     }): Promise<{
         logs: LogEntry[] | string;
+    } | {
+        count: number;
     }>;
     /**
      * Stream runtime logs for a service by polling the logs endpoint.
@@ -609,6 +876,9 @@ type ResolveScope = {
     kind: 'envVar';
     teamId: number;
     serviceId: number;
+} | {
+    kind: 'environment';
+    teamId: number;
 } | {
     kind: 'cronExecution';
     teamId: number;
@@ -630,10 +900,18 @@ declare class HostStack {
     readonly domains: DomainsResource;
     /** Manage service environment variables. */
     readonly envVars: EnvVarsResource;
+    /** v66: manage environments (production/staging/development/preview) per project. */
+    readonly environments: EnvironmentsResource;
     /** Manage cron job executions. */
     readonly cron: CronResource;
     /** Manage persistent disks attached to services. */
     readonly volumes: VolumesResource;
+    /**
+     * Manage notification channels — Slack/Discord webhooks + email
+     * recipients with per-channel event filters. Used for deploy
+     * failures, restart loops, ACME failures, git auth losses, etc.
+     */
+    readonly notifications: NotificationsResource;
     constructor(options: HostStackOptions);
     /**
      * Make an authenticated request to the HostStack API.
@@ -697,4 +975,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 CreateProjectInput, type CreateServiceInput, type CronExecution, type Database, type DatabaseCredentials, type Deploy, type Domain, type EnvVar, HostStack, HostStackError, type HostStackOptions, type LogEntry$1 as LogEntry, type MeResponse, NotFoundError, 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 UpdateProjectInput, type UpdateServiceConfigInput, type UpdateServiceInput, type User, buildPaginationQuery, wrapArray };
+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 };