@hoststack.dev/sdk 0.3.0 → 0.5.0

package/README.md

@@ -53,17 +53,21 @@ Generate an API key from your [HostStack dashboard → Settings → API Keys](ht
 
 ## Resources
 
-| Resource | Methods |
-| --- | --- |
-| `client.projects` | `list`, `get`, `create`, `update`, `delete` |
-| `client.services` | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getMetrics`, `getConfig`, `updateConfig`, `getRuntimeLogs`, `streamLogs` |
-| `client.deploys` | `list`, `get`, `trigger`, `cancel`, `rollback`, `getLogs` |
-| `client.databases` | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getCredentials`, `resetPassword` |
-| `client.domains` | `list`, `add`, `update`, `remove`, `verify` |
-| `client.envVars` | `list`, `create`, `update`, `delete`, `bulkSet` |
-| `client.cron` | `list`, `get`, `trigger` |
-
-Every method's first argument is `teamId: number`. Full API reference: **[hoststack.dev/docs/sdk](https://hoststack.dev/docs/sdk)**.
+| Resource              | Methods                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.projects`     | `list`, `get`, `create`, `update`, `delete`                                                                                                 |
+| `client.services`     | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getMetrics`, `getConfig`, `updateConfig`, `getRuntimeLogs`, `streamLogs` |
+| `client.deploys`      | `list`, `get`, `trigger`, `cancel`, `rollback`, `promote`, `getLogs`                                                                        |
+| `client.databases`    | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getCredentials`, `resetPassword`                                         |
+| `client.domains`      | `list`, `add`, `update`, `remove`, `verify`                                                                                                 |
+| `client.envVars`      | `list`, `create`, `update`, `delete`, `bulkSet`                                                                                             |
+| `client.volumes`      | `list`, `create`, `update`, `delete`                                                                                                        |
+| `client.environments` | `list`, `get`, `create`, `update`, `delete`                                                                                                 |
+| `client.cron`         | `list`, `get`, `trigger`                                                                                                                    |
+
+Every method's first argument is the team id — accepts either the numeric id or the `team_…` publicId (the SDK resolves publicIds to numeric ids internally and caches the lookup). Full API reference: **[hoststack.dev/docs/sdk](https://hoststack.dev/docs/sdk)**.
+
+`client.deploys.promote(teamId, serviceId, deployId, targetEnvironmentId)` performs image-based promotion: it pins the same built image into a sibling environment without rebuilding.
 
 ## Error handling
 
@@ -94,7 +98,8 @@ try {
 ## Related packages
 
 - **[@hoststack.dev/cli](https://www.npmjs.com/package/@hoststack.dev/cli)** — command-line interface for HostStack
-- **[Terraform provider](https://github.com/gethoststack/terraform-provider-hoststack)** — manage HostStack resources as IaC
+- **[@hoststack.dev/mcp](https://www.npmjs.com/package/@hoststack.dev/mcp)** — MCP server for Claude, Cursor, and other AI agents
+- **Terraform provider** — see [hoststack.dev/docs](https://hoststack.dev/docs) for installation and resource reference
 
 ## Support
 

package/dist/index.cjs

@@ -184,6 +184,24 @@ var DeploysResource = class {
     });
     return this.client.request("POST", `/api/services/${tid}/${sid}/deploys/${did}/rollback`);
   }
+  /**
+   * 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.
+   */
+  async promote(teamId, serviceId, deployId, targetEnvironmentId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
+    const did = await this.client.resolveId(deployId, {
+      kind: "deploy",
+      teamId: tid,
+      serviceId: sid
+    });
+    return this.client.request("POST", `/api/services/${tid}/${sid}/deploys/${did}/promote`, {
+      targetEnvironmentId
+    });
+  }
   /**
    * Get build logs for a deploy.
    *
@@ -245,6 +263,50 @@ var DomainsResource = class {
   }
 };
 
+// src/resources/environments.ts
+var EnvironmentsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all environments for a project. */
+  async list(teamId, projectId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
+    return this.client.request("GET", `/api/environments/${tid}/${pid}`);
+  }
+  /** Get a single environment by id. */
+  async get(teamId, projectId, envId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
+    const eid = await this.client.resolveId(envId, { kind: "environment", teamId: tid });
+    return this.client.request("GET", `/api/environments/${tid}/${pid}/${eid}`);
+  }
+  /** Create a new environment in the given project. */
+  async create(teamId, projectId, data) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
+    return this.client.request("POST", `/api/environments/${tid}/${pid}`, data);
+  }
+  /** Update environment metadata (name, default flag, protected flag). */
+  async update(teamId, projectId, envId, data) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
+    const eid = await this.client.resolveId(envId, { kind: "environment", teamId: tid });
+    return this.client.request("PATCH", `/api/environments/${tid}/${pid}/${eid}`, data);
+  }
+  /**
+   * 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.
+   */
+  async delete(teamId, projectId, envId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
+    const eid = await this.client.resolveId(envId, { kind: "environment", teamId: tid });
+    return this.client.request("DELETE", `/api/environments/${tid}/${pid}/${eid}`);
+  }
+};
+
 // src/resources/env-vars.ts
 var EnvVarsResource = class {
   constructor(client) {
@@ -292,6 +354,65 @@ var EnvVarsResource = class {
   }
 };
 
+// src/resources/notifications.ts
+var NotificationsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List notification channels for the team. Webhook URLs are
+   * server-side masked in the response so this is safe to log.
+   */
+  async listChannels(teamId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    return this.client.request("GET", `/api/notifications/${tid}/channels`);
+  }
+  /**
+   * 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.
+   */
+  async createChannel(teamId, data) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    return this.client.request("POST", `/api/notifications/${tid}/channels`, data);
+  }
+  /**
+   * 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.
+   */
+  async updateChannel(teamId, channelId, data) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    return this.client.request(
+      "PATCH",
+      `/api/notifications/${tid}/channels/${channelId}`,
+      data
+    );
+  }
+  /** Delete a notification channel. */
+  async deleteChannel(teamId, channelId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    return this.client.request("DELETE", `/api/notifications/${tid}/channels/${channelId}`);
+  }
+  /**
+   * Fire a test event to the channel so the user can confirm the
+   * webhook is wired correctly. Returns the dispatch outcome.
+   */
+  async testChannel(teamId, channelId) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    return this.client.request(
+      "POST",
+      `/api/notifications/${tid}/channels/${channelId}/test`
+    );
+  }
+};
+
 // src/resources/projects.ts
 var ProjectsResource = class {
   constructor(client) {
@@ -335,7 +456,7 @@ async function* streamLogsViaPolling(fetch2, basePath, options = {}) {
   const buildPath = (lines, since) => {
     const params = new URLSearchParams();
     if (options.stream) params.set("stream", options.stream);
-    if (lines !== void 0) params.set("lines", String(lines));
+    if (lines !== void 0) params.set("limit", String(lines));
     if (since) params.set("since", since);
     const qs = params.toString();
     return `${basePath}${qs ? `?${qs}` : ""}`;
@@ -389,10 +510,23 @@ var ServicesResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List all services for the active team. */
-  async list(teamId) {
+  /**
+   * 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.
+   */
+  async list(teamId, filters) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
-    return this.client.request("GET", `/api/services/${tid}`);
+    const params = new URLSearchParams();
+    if (filters?.projectId !== void 0) params.set("projectId", String(filters.projectId));
+    if (filters?.environmentId !== void 0)
+      params.set("environmentId", String(filters.environmentId));
+    if (filters?.status) params.set("status", filters.status);
+    if (filters?.type) params.set("type", filters.type);
+    const qs = params.toString();
+    return this.client.request("GET", `/api/services/${tid}${qs ? `?${qs}` : ""}`);
   }
   /** Get a single service by ID. */
   async get(teamId, serviceId) {
@@ -435,6 +569,25 @@ var ServicesResource = class {
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     return this.client.request("GET", `/api/services/${tid}/${sid}/metrics`);
   }
+  /**
+   * 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.
+   */
+  async getMetricsHistory(teamId, serviceId, options) {
+    const tid = await this.client.resolveId(teamId, { kind: "team" });
+    const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
+    const params = new URLSearchParams();
+    if (options?.from) params.set("from", options.from);
+    if (options?.to) params.set("to", options.to);
+    const qs = params.toString();
+    return this.client.request(
+      "GET",
+      `/api/services/${tid}/${sid}/metrics/history${qs ? `?${qs}` : ""}`
+    );
+  }
   /** Get service configuration. */
   async getConfig(teamId, serviceId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
@@ -447,14 +600,30 @@ var ServicesResource = class {
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     return this.client.request("PATCH", `/api/services/${tid}/${sid}/config`, data);
   }
-  /** 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.
+   */
   async getRuntimeLogs(teamId, serviceId, options) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     const params = new URLSearchParams();
-    if (options?.lines) params.set("lines", String(options.lines));
+    const lim = options?.limit ?? options?.lines;
+    if (lim != null) params.set("limit", String(lim));
     if (options?.since) params.set("since", options.since);
+    if (options?.until) params.set("until", options.until);
     if (options?.stream) params.set("stream", options.stream);
+    if (options?.level) params.set("level", options.level);
+    const grep = options?.grep ?? options?.search;
+    if (grep) params.set("search", grep);
+    if (options?.countOnly) params.set("count_only", "1");
     const qs = params.toString();
     return this.client.request(
       "GET",
@@ -477,11 +646,7 @@ var ServicesResource = class {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     const basePath = `/api/services/${tid}/${sid}/runtime-logs`;
-    yield* streamLogsViaPolling(
-      (path) => this.client.request("GET", path),
-      basePath,
-      options
-    );
+    yield* streamLogsViaPolling((path) => this.client.request("GET", path), basePath, options);
   }
 };
 
@@ -543,6 +708,7 @@ var PREFIX = {
   domain: "dom_",
   volume: "vol_",
   envVar: "env_",
+  environment: "environment_",
   cronExecution: "cjob_"
 };
 var HostStack = class {
@@ -562,10 +728,18 @@ var HostStack = class {
   domains;
   /** Manage service environment variables. */
   envVars;
+  /** v66: manage environments (production/staging/development/preview) per project. */
+  environments;
   /** Manage cron job executions. */
   cron;
   /** Manage persistent disks attached to services. */
   volumes;
+  /**
+   * 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.
+   */
+  notifications;
   constructor(options) {
     if (!options.apiKey) {
       throw new Error("apiKey is required");
@@ -578,8 +752,10 @@ var HostStack = class {
     this.databases = new DatabasesResource(this);
     this.domains = new DomainsResource(this);
     this.envVars = new EnvVarsResource(this);
+    this.environments = new EnvironmentsResource(this);
     this.cron = new CronResource(this);
     this.volumes = new VolumesResource(this);
+    this.notifications = new NotificationsResource(this);
   }
   /**
    * Make an authenticated request to the HostStack API.
@@ -671,17 +847,11 @@ var HostStack = class {
         return r.services ?? [];
       }
       case "deploy": {
-        const r = await this.request(
-          "GET",
-          `/api/services/${scope.teamId}/${scope.serviceId}/deploys?perPage=100`
-        );
+        const r = await this.request("GET", `/api/services/${scope.teamId}/${scope.serviceId}/deploys?perPage=100`);
         return r.data ?? [];
       }
       case "database": {
-        const r = await this.request(
-          "GET",
-          `/api/databases/${scope.teamId}`
-        );
+        const r = await this.request("GET", `/api/databases/${scope.teamId}`);
         return r.databases ?? [];
       }
       case "domain": {
@@ -706,6 +876,15 @@ var HostStack = class {
         const r = await this.request("GET", `/api/services/${scope.teamId}/${scope.serviceId}/cron-executions`);
         return r.executions ?? [];
       }
+      case "environment": {
+        const projectsRes = await this.request("GET", `/api/projects/${scope.teamId}`);
+        const envs = [];
+        for (const p of projectsRes.projects ?? []) {
+          const r = await this.request("GET", `/api/environments/${scope.teamId}/${p.id}`);
+          envs.push(...r.environments ?? []);
+        }
+        return envs;
+      }
     }
   }
 };
@@ -717,6 +896,7 @@ function cacheScope(scope) {
     case "service":
     case "database":
     case "domain":
+    case "environment":
       return `${scope.kind}:${scope.teamId}`;
     case "deploy":
     case "volume":