@hoststack.dev/sdk 0.8.0 → 0.8.1

package/README.md

@@ -11,7 +11,7 @@ Official TypeScript SDK for [HostStack](https://hoststack.dev) — the European
 - **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)
+- **Source:** [github.com/miccidk/hoststack](https://github.com/miccidk/hoststack/tree/master/packages/sdk)
 
 ## Installation
 
@@ -53,18 +53,18 @@ 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`, `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`                                                                                                                    |
-| `client.notifications` | `listChannels`, `createChannel`, `updateChannel`, `deleteChannel`, `testChannel`                                                            |
+| Resource               | Methods                                                                                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.projects`      | `list`, `get`, `create`, `update`, `delete`                                                                                                                      |
+| `client.services`      | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getMetrics`, `getMetricsHistory`, `getConfig`, `updateConfig`, `getRuntimeLogs`, `streamLogs` |
+| `client.deploys`       | `list`, `get`, `trigger`, `cancel`, `rollback`, `promote`, `getLogs`                                                                                             |
+| `client.databases`     | `list`, `get`, `create`, `update`, `delete`, `suspend`, `resume`, `getCredentials`, `resetPassword`, `query`, `upgradeToHa`                                      |
+| `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`                                                                                                                                         |
+| `client.notifications` | `listChannels`, `createChannel`, `updateChannel`, `deleteChannel`, `testChannel`                                                                                 |
 
 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)**.
 
@@ -76,7 +76,9 @@ Every method's first argument is the team id — accepts either the numeric id o
 import {
 	HostStack,
 	AuthenticationError,
+	ForbiddenError,
 	NotFoundError,
+	ConflictError,
 	RateLimitError,
 	HostStackError,
 } from '@hoststack.dev/sdk';
@@ -87,11 +89,15 @@ try {
 	if (err instanceof NotFoundError) {
 		// 404
 	} else if (err instanceof AuthenticationError) {
-		// 401/403
+		// 401 — API key missing or expired
+	} else if (err instanceof ForbiddenError) {
+		// 403 — key lacks the required scope (e.g. deploy_only trying to mutate)
+	} else if (err instanceof ConflictError) {
+		// 409 — resource state prevents the op (already exists, in-flight migration, …)
 	} else if (err instanceof RateLimitError) {
-		// 429 — err.retryAfter is seconds to wait
+		// 429 — err.retryAfter is seconds to wait (from Retry-After header), or undefined
 	} else if (err instanceof HostStackError) {
-		// any other API error — err.status, err.body
+		// any other API error — err.statusCode and err.body are available
 	}
 }
 ```
@@ -104,7 +110,7 @@ try {
 
 ## Support
 
-- Issues: [github.com/gethoststack/sdk/issues](https://github.com/gethoststack/sdk/issues)
+- Issues: [github.com/miccidk/hoststack/issues](https://github.com/miccidk/hoststack/issues)
 - Docs: [hoststack.dev/docs](https://hoststack.dev/docs)
 - Homepage: [hoststack.dev](https://hoststack.dev)
 

package/dist/index.cjs

@@ -3,28 +3,49 @@
 // src/errors.ts
 var HostStackError = class extends Error {
   statusCode;
-  constructor(statusCode, message) {
+  /** Raw response body, if it parsed as JSON. Useful for surfacing field-level validation errors. */
+  body;
+  constructor(statusCode, message, body) {
     super(message);
     this.name = "HostStackError";
     this.statusCode = statusCode;
+    this.body = body;
   }
 };
 var AuthenticationError = class extends HostStackError {
-  constructor(message = "Authentication failed. Check your API key.") {
-    super(401, message);
+  constructor(message = "Authentication failed \u2014 check your API key.", body) {
+    super(401, message, body);
     this.name = "AuthenticationError";
   }
 };
+var ForbiddenError = class extends HostStackError {
+  constructor(message = "Permission denied \u2014 API key lacks the required scope.", body) {
+    super(403, message, body);
+    this.name = "ForbiddenError";
+  }
+};
 var NotFoundError = class extends HostStackError {
-  constructor(message = "Resource not found.") {
-    super(404, message);
+  constructor(message = "Resource not found.", body) {
+    super(404, message, body);
     this.name = "NotFoundError";
   }
 };
+var ConflictError = class extends HostStackError {
+  constructor(message = "Conflict \u2014 the resource state prevents this operation.", body) {
+    super(409, message, body);
+    this.name = "ConflictError";
+  }
+};
 var RateLimitError = class extends HostStackError {
-  constructor(message = "Rate limit exceeded. Try again later.") {
-    super(429, message);
+  /**
+   * Seconds to wait before retrying, parsed from the `Retry-After` response
+   * header. `undefined` if the server didn't send one.
+   */
+  retryAfter;
+  constructor(message = "Rate limit exceeded \u2014 back off and retry.", retryAfter, body) {
+    super(429, message, body);
     this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
   }
 };
 
@@ -69,9 +90,15 @@ var DatabasesResource = class {
   constructor(client) {
     this.client = client;
   }
-  /** List all databases for a project. */
+  /**
+   * List databases for the team. Pass `projectId` to scope to one
+   * project; omit it to list every database the team owns.
+   */
   async list(teamId, projectId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
+    if (projectId === void 0) {
+      return this.client.request("GET", `/api/databases/${tid}`);
+    }
     const pid = await this.client.resolveId(projectId, { kind: "project", teamId: tid });
     return this.client.request("GET", `/api/databases/${tid}?projectId=${pid}`);
   }
@@ -374,22 +401,24 @@ var EnvVarsResource = class {
   async update(teamId, serviceId, envVarId, data) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
-    const eid = await this.client.resolveId(envVarId, {
-      kind: "envVar",
-      teamId: tid,
-      serviceId: sid
-    });
+    const eid = typeof envVarId === "number" ? envVarId : Number.parseInt(envVarId, 10);
+    if (Number.isNaN(eid)) {
+      throw new Error(
+        `Invalid envVarId "${envVarId}": expected a numeric id (env vars have no publicId \u2014 read it from list()).`
+      );
+    }
     return this.client.request("PATCH", `/api/services/${tid}/${sid}/env/${eid}`, data);
   }
   /** Delete an environment variable. */
   async delete(teamId, serviceId, envVarId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
-    const eid = await this.client.resolveId(envVarId, {
-      kind: "envVar",
-      teamId: tid,
-      serviceId: sid
-    });
+    const eid = typeof envVarId === "number" ? envVarId : Number.parseInt(envVarId, 10);
+    if (Number.isNaN(eid)) {
+      throw new Error(
+        `Invalid envVarId "${envVarId}": expected a numeric id (env vars have no publicId \u2014 read it from list()).`
+      );
+    }
     return this.client.request("DELETE", `/api/services/${tid}/${sid}/env/${eid}`);
   }
   /** Bulk set environment variables (create or update). */
@@ -606,7 +635,13 @@ var ServicesResource = class {
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
     return this.client.request("POST", `/api/services/${tid}/${sid}/resume`);
   }
-  /** Get service metrics. */
+  /**
+   * Get the latest metrics snapshot for a service.
+   *
+   * Returns `metrics: null` before the first agent sample lands;
+   * `serverOverview: null` when the service is not currently placed
+   * (suspended, between deploys, etc).
+   */
   async getMetrics(teamId, serviceId) {
     const tid = await this.client.resolveId(teamId, { kind: "team" });
     const sid = await this.client.resolveId(serviceId, { kind: "service", teamId: tid });
@@ -750,8 +785,7 @@ var PREFIX = {
   database: "db_",
   domain: "dom_",
   volume: "vol_",
-  envVar: "env_",
-  environment: "environment_",
+  environment: "env_",
   cronExecution: "cjob_"
 };
 var HostStack = class {
@@ -822,13 +856,20 @@ var HostStack = class {
       const message = data.error ?? `HTTP ${res.status}`;
       switch (res.status) {
         case 401:
-          throw new AuthenticationError(message);
+          throw new AuthenticationError(message, data);
+        case 403:
+          throw new ForbiddenError(message, data);
         case 404:
-          throw new NotFoundError(message);
-        case 429:
-          throw new RateLimitError(message);
+          throw new NotFoundError(message, data);
+        case 409:
+          throw new ConflictError(message, data);
+        case 429: {
+          const header = res.headers.get("Retry-After");
+          const retryAfter = header && /^\d+$/.test(header) ? Number(header) : void 0;
+          throw new RateLimitError(message, retryAfter, data);
+        }
         default:
-          throw new HostStackError(res.status, message);
+          throw new HostStackError(res.status, message, data);
       }
     }
     if (res.status === 204) {
@@ -904,13 +945,6 @@ var HostStack = class {
         );
         return r.domains ?? [];
       }
-      case "envVar": {
-        const r = await this.request(
-          "GET",
-          `/api/services/${scope.teamId}/${scope.serviceId}/env`
-        );
-        return r.envVars ?? [];
-      }
       case "volume": {
         const r = await this.request("GET", `/api/services/${scope.teamId}/${scope.serviceId}/volumes`);
         return r.volumes ?? [];
@@ -943,7 +977,6 @@ function cacheScope(scope) {
       return `${scope.kind}:${scope.teamId}`;
     case "deploy":
     case "volume":
-    case "envVar":
     case "cronExecution":
       return `${scope.kind}:${scope.teamId}:${scope.serviceId}`;
   }
@@ -971,6 +1004,8 @@ function wrapArray(items, params) {
 }
 
 exports.AuthenticationError = AuthenticationError;
+exports.ConflictError = ConflictError;
+exports.ForbiddenError = ForbiddenError;
 exports.HostStack = HostStack;
 exports.HostStackError = HostStackError;
 exports.NotFoundError = NotFoundError;