@hoststack.dev/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HostStack Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @hoststack.dev/sdk
+
+Official TypeScript SDK for [HostStack](https://hoststack.dev) — the European PaaS for deploying web services, databases, cron jobs, and domains on Hetzner infrastructure.
+
+> Think Render.com, but hosted in Europe, built for developers who care about latency and data residency.
+
+[![npm version](https://img.shields.io/npm/v/@hoststack.dev/sdk.svg)](https://www.npmjs.com/package/@hoststack.dev/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@hoststack.dev/sdk.svg)](https://www.npmjs.com/package/@hoststack.dev/sdk)
+[![MIT license](https://img.shields.io/npm/l/@hoststack.dev/sdk.svg)](./LICENSE)
+
+- **Website:** [hoststack.dev](https://hoststack.dev)
+- **Documentation:** [hoststack.dev/docs](https://hoststack.dev/docs)
+- **SDK reference:** [hoststack.dev/docs/sdk](https://hoststack.dev/docs/sdk)
+- **Source:** [github.com/gethoststack/sdk](https://github.com/gethoststack/sdk)
+
+## Installation
+
+```bash
+npm install @hoststack.dev/sdk
+# or
+bun add @hoststack.dev/sdk
+# or
+pnpm add @hoststack.dev/sdk
+```
+
+Requires Node.js 18+ (uses native `fetch`). Works in Bun and Deno too.
+
+## Quick start
+
+```ts
+import { HostStack } from '@hoststack.dev/sdk';
+
+const client = new HostStack({
+	apiKey: 'hs_live_your_api_key',
+});
+
+const teamId = 1;
+
+// List your services
+const { services } = await client.services.list(teamId);
+
+// Trigger a deploy
+const { deploy } = await client.deploys.trigger(teamId, 'svc_abc123');
+
+// Stream runtime logs
+const ac = new AbortController();
+for await (const entry of client.services.streamLogs(teamId, 'svc_abc123', { signal: ac.signal })) {
+	console.log(entry.timestamp, entry.message);
+}
+```
+
+Generate an API key from your [HostStack dashboard → Settings → API Keys](https://hoststack.dev).
+
+## 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)**.
+
+## Error handling
+
+```ts
+import {
+	HostStack,
+	AuthenticationError,
+	NotFoundError,
+	RateLimitError,
+	HostStackError,
+} from '@hoststack.dev/sdk';
+
+try {
+	await client.services.get(teamId, 'svc_missing');
+} catch (err) {
+	if (err instanceof NotFoundError) {
+		// 404
+	} else if (err instanceof AuthenticationError) {
+		// 401/403
+	} else if (err instanceof RateLimitError) {
+		// 429 — err.retryAfter is seconds to wait
+	} else if (err instanceof HostStackError) {
+		// any other API error — err.status, err.body
+	}
+}
+```
+
+## 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
+
+## Support
+
+- Issues: [github.com/gethoststack/sdk/issues](https://github.com/gethoststack/sdk/issues)
+- Docs: [hoststack.dev/docs](https://hoststack.dev/docs)
+- Homepage: [hoststack.dev](https://hoststack.dev)
+
+## License
+
+MIT © [HostStack Contributors](https://hoststack.dev)

package/dist/index.cjs

@@ -0,0 +1,482 @@
+'use strict';
+
+// src/errors.ts
+var HostStackError = class extends Error {
+  statusCode;
+  constructor(statusCode, message) {
+    super(message);
+    this.name = "HostStackError";
+    this.statusCode = statusCode;
+  }
+};
+var AuthenticationError = class extends HostStackError {
+  constructor(message = "Authentication failed. Check your API key.") {
+    super(401, message);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends HostStackError {
+  constructor(message = "Resource not found.") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends HostStackError {
+  constructor(message = "Rate limit exceeded. Try again later.") {
+    super(429, message);
+    this.name = "RateLimitError";
+  }
+};
+
+// src/resources/cron.ts
+var CronResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List cron executions for a service. */
+  async list(teamId, serviceId, options) {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    return this.client.request(
+      "GET",
+      `/api/services/${teamId}/${serviceId}/cron-executions${qs ? `?${qs}` : ""}`
+    );
+  }
+  /** Get a single cron execution by ID. */
+  async get(teamId, serviceId, executionId) {
+    return this.client.request(
+      "GET",
+      `/api/services/${teamId}/${serviceId}/cron-executions/${executionId}`
+    );
+  }
+  /** Trigger an immediate cron execution. */
+  async trigger(teamId, serviceId) {
+    return this.client.request(
+      "POST",
+      `/api/services/${teamId}/${serviceId}/cron-executions/trigger`
+    );
+  }
+};
+
+// src/resources/databases.ts
+var DatabasesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List all databases for a project. */
+  async list(teamId, projectId) {
+    return this.client.request("GET", `/api/databases/${teamId}?projectId=${projectId}`);
+  }
+  /** Get a single database by ID. */
+  async get(teamId, databaseId) {
+    return this.client.request("GET", `/api/databases/${teamId}/${databaseId}`);
+  }
+  /** Create a new database. */
+  async create(teamId, data) {
+    return this.client.request("POST", `/api/databases/${teamId}`, data);
+  }
+  /** Update a database. */
+  async update(teamId, databaseId, data) {
+    return this.client.request("PATCH", `/api/databases/${teamId}/${databaseId}`, data);
+  }
+  /** Delete a database. */
+  async delete(teamId, databaseId) {
+    return this.client.request("DELETE", `/api/databases/${teamId}/${databaseId}`);
+  }
+  /** Suspend a database. */
+  async suspend(teamId, databaseId) {
+    return this.client.request("POST", `/api/databases/${teamId}/${databaseId}/suspend`);
+  }
+  /** Resume a suspended database. */
+  async resume(teamId, databaseId) {
+    return this.client.request("POST", `/api/databases/${teamId}/${databaseId}/resume`);
+  }
+  /** Get connection credentials. */
+  async getCredentials(teamId, databaseId) {
+    return this.client.request("GET", `/api/databases/${teamId}/${databaseId}/credentials`);
+  }
+  /** Reset the database password. */
+  async resetPassword(teamId, databaseId) {
+    return this.client.request("POST", `/api/databases/${teamId}/${databaseId}/reset-password`);
+  }
+};
+
+// src/resources/deploys.ts
+var DeploysResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List deploys for a service. */
+  async list(teamId, serviceId) {
+    return this.client.request("GET", `/api/services/${teamId}/${serviceId}/deploys`);
+  }
+  /** Get a single deploy by ID. */
+  async get(teamId, serviceId, deployId) {
+    return this.client.request(
+      "GET",
+      `/api/services/${teamId}/${serviceId}/deploys/${deployId}`
+    );
+  }
+  /** Trigger a new deploy. */
+  async trigger(teamId, serviceId, data) {
+    return this.client.request(
+      "POST",
+      `/api/services/${teamId}/${serviceId}/deploys`,
+      data ?? {}
+    );
+  }
+  /** Cancel an in-progress deploy. */
+  async cancel(teamId, serviceId, deployId) {
+    return this.client.request(
+      "POST",
+      `/api/services/${teamId}/${serviceId}/deploys/${deployId}/cancel`
+    );
+  }
+  /** Rollback to a previous deploy. */
+  async rollback(teamId, serviceId, deployId) {
+    return this.client.request(
+      "POST",
+      `/api/services/${teamId}/${serviceId}/deploys/${deployId}/rollback`
+    );
+  }
+  /** Get build logs for a deploy. */
+  async getLogs(teamId, serviceId, deployId) {
+    return this.client.request(
+      "GET",
+      `/api/services/${teamId}/${serviceId}/deploys/${deployId}/logs`
+    );
+  }
+};
+
+// src/resources/domains.ts
+var DomainsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List all domains for the active team. */
+  async list(teamId) {
+    return this.client.request("GET", `/api/domains/${teamId}`);
+  }
+  /** Add a custom domain. */
+  async add(teamId, data) {
+    return this.client.request("POST", `/api/domains/${teamId}`, data);
+  }
+  /** Update a domain. */
+  async update(teamId, domainId, data) {
+    return this.client.request("PATCH", `/api/domains/${teamId}/${domainId}`, data);
+  }
+  /** Remove a domain. */
+  async remove(teamId, domainId) {
+    return this.client.request("DELETE", `/api/domains/${teamId}/${domainId}`);
+  }
+  /** Verify domain DNS configuration. */
+  async verify(teamId, domainId) {
+    return this.client.request("POST", `/api/domains/${teamId}/${domainId}/verify`);
+  }
+};
+
+// src/resources/env-vars.ts
+var EnvVarsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List all environment variables for a service. */
+  async list(teamId, serviceId) {
+    return this.client.request("GET", `/api/services/${teamId}/${serviceId}/env`);
+  }
+  /** Create a new environment variable. */
+  async create(teamId, serviceId, data) {
+    return this.client.request("POST", `/api/services/${teamId}/${serviceId}/env`, data);
+  }
+  /** Update an environment variable. */
+  async update(teamId, serviceId, envVarId, data) {
+    return this.client.request(
+      "PATCH",
+      `/api/services/${teamId}/${serviceId}/env/${envVarId}`,
+      data
+    );
+  }
+  /** Delete an environment variable. */
+  async delete(teamId, serviceId, envVarId) {
+    return this.client.request(
+      "DELETE",
+      `/api/services/${teamId}/${serviceId}/env/${envVarId}`
+    );
+  }
+  /** Bulk set environment variables (create or update). */
+  async bulkSet(teamId, serviceId, data) {
+    return this.client.request("PUT", `/api/services/${teamId}/${serviceId}/env/bulk`, data);
+  }
+};
+
+// src/resources/projects.ts
+var ProjectsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List all projects for the active team. */
+  async list(teamId) {
+    return this.client.request("GET", `/api/projects/${teamId}`);
+  }
+  /** Get a single project by ID. */
+  async get(teamId, projectId) {
+    return this.client.request("GET", `/api/projects/${teamId}/${projectId}`);
+  }
+  /** Create a new project. */
+  async create(teamId, data) {
+    return this.client.request("POST", `/api/projects/${teamId}`, data);
+  }
+  /** Update a project. */
+  async update(teamId, projectId, data) {
+    return this.client.request("PATCH", `/api/projects/${teamId}/${projectId}`, data);
+  }
+  /** Delete a project. */
+  async delete(teamId, projectId) {
+    return this.client.request("DELETE", `/api/projects/${teamId}/${projectId}`);
+  }
+};
+
+// src/streaming.ts
+async function* streamLogsViaPolling(fetch2, basePath, options = {}) {
+  const pollInterval = options.pollInterval ?? 2e3;
+  const initialLines = options.initialLines ?? 100;
+  let lastTimestamp = null;
+  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 (since) params.set("since", since);
+    const qs = params.toString();
+    return `${basePath}${qs ? `?${qs}` : ""}`;
+  };
+  const initialData = await fetch2(buildPath(initialLines));
+  const initial = normalizeEntries(initialData.logs);
+  for (const entry of initial) {
+    yield entry;
+    if (entry.timestamp > (lastTimestamp ?? "")) {
+      lastTimestamp = entry.timestamp;
+    }
+  }
+  while (!options.signal?.aborted) {
+    await sleep(pollInterval, options.signal);
+    if (options.signal?.aborted) break;
+    const sinceTs = lastTimestamp ? new Date(lastTimestamp).toISOString() : void 0;
+    const data = await fetch2(buildPath(void 0, sinceTs)).catch(() => ({ logs: [] }));
+    const entries = normalizeEntries(data.logs);
+    for (const entry of entries) {
+      if (!lastTimestamp || entry.timestamp > lastTimestamp) {
+        yield entry;
+        lastTimestamp = entry.timestamp;
+      }
+    }
+  }
+}
+function normalizeEntries(logs) {
+  if (typeof logs === "string") {
+    const lines = logs.split("\n").filter(Boolean);
+    return lines.map((line) => ({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: line
+    }));
+  }
+  return logs;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    if (signal) {
+      signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      });
+    }
+  });
+}
+
+// src/resources/services.ts
+var ServicesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** List all services for the active team. */
+  async list(teamId) {
+    return this.client.request("GET", `/api/services/${teamId}`);
+  }
+  /** Get a single service by ID. */
+  async get(teamId, serviceId) {
+    return this.client.request("GET", `/api/services/${teamId}/${serviceId}`);
+  }
+  /** Create a new service. */
+  async create(teamId, data) {
+    return this.client.request("POST", `/api/services/${teamId}`, data);
+  }
+  /** Update a service. */
+  async update(teamId, serviceId, data) {
+    return this.client.request("PATCH", `/api/services/${teamId}/${serviceId}`, data);
+  }
+  /** Delete a service. */
+  async delete(teamId, serviceId) {
+    return this.client.request("DELETE", `/api/services/${teamId}/${serviceId}`);
+  }
+  /** Suspend a service. */
+  async suspend(teamId, serviceId) {
+    return this.client.request("POST", `/api/services/${teamId}/${serviceId}/suspend`);
+  }
+  /** Resume a suspended service. */
+  async resume(teamId, serviceId) {
+    return this.client.request("POST", `/api/services/${teamId}/${serviceId}/resume`);
+  }
+  /** Get service metrics. */
+  async getMetrics(teamId, serviceId) {
+    return this.client.request("GET", `/api/services/${teamId}/${serviceId}/metrics`);
+  }
+  /** Get service configuration. */
+  async getConfig(teamId, serviceId) {
+    return this.client.request("GET", `/api/services/${teamId}/${serviceId}/config`);
+  }
+  /** Update service configuration. */
+  async updateConfig(teamId, serviceId, data) {
+    return this.client.request("PATCH", `/api/services/${teamId}/${serviceId}/config`, data);
+  }
+  /** Get runtime logs for a service. */
+  async getRuntimeLogs(teamId, serviceId, options) {
+    const params = new URLSearchParams();
+    if (options?.lines) params.set("lines", String(options.lines));
+    if (options?.since) params.set("since", options.since);
+    if (options?.stream) params.set("stream", options.stream);
+    const qs = params.toString();
+    return this.client.request(
+      "GET",
+      `/api/services/${teamId}/${serviceId}/runtime-logs${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * Stream runtime logs for a service by polling the logs endpoint.
+   * Yields log entries as they appear. Use an AbortController to stop.
+   *
+   * @example
+   * ```ts
+   * const ac = new AbortController();
+   * for await (const entry of client.services.streamLogs(teamId, serviceId, { signal: ac.signal })) {
+   *   console.log(entry.message);
+   * }
+   * ```
+   */
+  streamLogs(teamId, serviceId, options) {
+    const basePath = `/api/services/${teamId}/${serviceId}/runtime-logs`;
+    return streamLogsViaPolling(
+      (path) => this.client.request("GET", path),
+      basePath,
+      options
+    );
+  }
+};
+
+// src/client.ts
+var HostStack = class {
+  apiKey;
+  baseUrl;
+  /** Manage projects. */
+  projects;
+  /** Manage services (web, worker, cron). */
+  services;
+  /** Trigger and manage deployments. */
+  deploys;
+  /** Manage databases (Postgres, Redis). */
+  databases;
+  /** Manage custom domains. */
+  domains;
+  /** Manage service environment variables. */
+  envVars;
+  /** Manage cron job executions. */
+  cron;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("apiKey is required");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://api.hoststack.dev").replace(/\/$/, "");
+    this.projects = new ProjectsResource(this);
+    this.services = new ServicesResource(this);
+    this.deploys = new DeploysResource(this);
+    this.databases = new DatabasesResource(this);
+    this.domains = new DomainsResource(this);
+    this.envVars = new EnvVarsResource(this);
+    this.cron = new CronResource(this);
+  }
+  /**
+   * Make an authenticated request to the HostStack API.
+   * Used internally by resource classes. Can also be used for custom API calls.
+   */
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: "Unknown error" }));
+      const message = data.error ?? `HTTP ${res.status}`;
+      switch (res.status) {
+        case 401:
+          throw new AuthenticationError(message);
+        case 404:
+          throw new NotFoundError(message);
+        case 429:
+          throw new RateLimitError(message);
+        default:
+          throw new HostStackError(res.status, message);
+      }
+    }
+    if (res.status === 204) {
+      return void 0;
+    }
+    return res.json();
+  }
+};
+
+// src/pagination.ts
+function buildPaginationQuery(params) {
+  if (!params) return "";
+  const qs = new URLSearchParams();
+  if (params.limit !== void 0) qs.set("limit", String(params.limit));
+  if (params.offset !== void 0) qs.set("offset", String(params.offset));
+  const str = qs.toString();
+  return str ? `?${str}` : "";
+}
+function wrapArray(items, params) {
+  const limit = params?.limit ?? items.length;
+  const offset = params?.offset ?? 0;
+  return {
+    items,
+    total: items.length,
+    limit,
+    offset,
+    hasMore: false
+  };
+}
+
+exports.AuthenticationError = AuthenticationError;
+exports.HostStack = HostStack;
+exports.HostStackError = HostStackError;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;
+exports.buildPaginationQuery = buildPaginationQuery;
+exports.wrapArray = wrapArray;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map