@homecloud-platform/sdk 0.4.9 → 0.5.0

package/src/credentials.js

@@ -0,0 +1,101 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { DEFAULT_APEX, DEFAULT_PROFILE, envFirst } = require("./defaults");
+
+function homecloudDir() {
+  const override = envFirst("HOMECLOUD_CONFIG_DIR", "HC_CONFIG_DIR");
+  if (override) return path.resolve(override.replace(/^~(?=\/|\\)/, os.homedir()));
+  return path.join(os.homedir(), ".homecloud");
+}
+
+function credentialsPath() {
+  const override = envFirst("HOMECLOUD_CREDENTIALS_FILE", "HC_CREDENTIALS_FILE");
+  if (override) return path.resolve(override.replace(/^~(?=\/|\\)/, os.homedir()));
+  return path.join(homecloudDir(), "credentials");
+}
+
+function sessionPath() {
+  const override = envFirst("HOMECLOUD_SESSION_FILE", "HC_SESSION_FILE");
+  if (override) return path.resolve(override.replace(/^~(?=\/|\\)/, os.homedir()));
+  return path.join(homecloudDir(), "session");
+}
+
+function loadCredentials(filePath = credentialsPath()) {
+  if (!fs.existsSync(filePath)) {
+    return { version: 2, default_profile: DEFAULT_PROFILE, profiles: {} };
+  }
+  const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  if (!raw || typeof raw !== "object") throw new Error("Invalid credentials file");
+  if (raw.profiles && typeof raw.profiles === "object") {
+    return {
+      version: Number(raw.version || 2),
+      default_profile: raw.default_profile || DEFAULT_PROFILE,
+      profiles: raw.profiles,
+    };
+  }
+  // legacy flat
+  return {
+    version: 2,
+    default_profile: DEFAULT_PROFILE,
+    profiles: { [DEFAULT_PROFILE]: raw },
+  };
+}
+
+function loadSession(filePath = sessionPath()) {
+  if (!fs.existsSync(filePath)) return { version: 1, profiles: {} };
+  const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return {
+    version: Number(raw.version || 1),
+    profiles: raw.profiles || {},
+  };
+}
+
+function saveSession(session, filePath = sessionPath()) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(session, null, 2) + "\n", "utf8");
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch (_) {}
+  return filePath;
+}
+
+function resolveProfile(name) {
+  const creds = loadCredentials();
+  const profileName =
+    name ||
+    envFirst("HOMECLOUD_PROFILE", "HC_PROFILE") ||
+    creds.default_profile ||
+    DEFAULT_PROFILE;
+  const profile = creds.profiles[profileName] || {};
+  const session = loadSession().profiles[profileName] || {};
+  return {
+    profileName,
+    apex: envFirst("HOMECLOUD_APEX", "HC_APEX") || profile.apex || DEFAULT_APEX,
+    accountId:
+      envFirst("HOMECLOUD_ACCOUNT_ID", "HC_ACCOUNT_ID") ||
+      profile.default_account_id ||
+      session.active_account_id ||
+      null,
+    accessKeyId:
+      envFirst("HOMECLOUD_ACCESS_KEY_ID", "HC_ACCESS_KEY_ID") || profile.access_key_id || null,
+    secretAccessKey:
+      envFirst("HOMECLOUD_SECRET_ACCESS_KEY", "HC_SECRET_ACCESS_KEY") ||
+      profile.secret_access_key ||
+      null,
+    accessToken: session.access_token || null,
+  };
+}
+
+module.exports = {
+  homecloudDir,
+  credentialsPath,
+  sessionPath,
+  loadCredentials,
+  loadSession,
+  saveSession,
+  resolveProfile,
+};

package/src/defaults.js

@@ -0,0 +1,47 @@
+"use strict";
+
+const DEFAULT_APEX = "holab.abrdns.com";
+const DEFAULT_PROFILE = "default";
+const WHOAMI_PATH = "/access-key/whoami";
+const WHOAMI_ACCOUNT_SENTINEL = "-";
+
+function soUrl(apex) {
+  return `https://so.${apex || DEFAULT_APEX}`;
+}
+function mqUrl(apex) {
+  return `https://mq.${apex || DEFAULT_APEX}`;
+}
+function secretsUrl(apex) {
+  return `https://secrets.${apex || DEFAULT_APEX}`;
+}
+function mailApiUrl(apex) {
+  return `https://mailapi.${apex || DEFAULT_APEX}`;
+}
+function consoleUrl(apex) {
+  return `https://console.${apex || DEFAULT_APEX}/api/v1`;
+}
+function functionUrl(name, apex) {
+  return `https://${String(name).trim().toLowerCase()}.func.${apex || DEFAULT_APEX}`;
+}
+
+function envFirst(...names) {
+  for (const name of names) {
+    const v = process.env[name];
+    if (v != null && String(v).trim() !== "") return v;
+  }
+  return null;
+}
+
+module.exports = {
+  DEFAULT_APEX,
+  DEFAULT_PROFILE,
+  WHOAMI_PATH,
+  WHOAMI_ACCOUNT_SENTINEL,
+  soUrl,
+  mqUrl,
+  secretsUrl,
+  mailApiUrl,
+  consoleUrl,
+  functionUrl,
+  envFirst,
+};

package/src/errors.js

@@ -0,0 +1,166 @@
+"use strict";
+
+class HomeCloudError extends Error {
+  constructor(message, { statusCode = null, detail = null } = {}) {
+    super(message);
+    this.name = "HomeCloudError";
+    this.statusCode = statusCode;
+    this.detail = detail;
+  }
+
+  get errorPayload() {
+    if (!this.detail || typeof this.detail !== "object") return null;
+    const error = this.detail.error;
+    if (error && typeof error === "object" && error.code) {
+      return {
+        code: String(error.code),
+        message: String(error.message || error.code),
+        details: error.details && typeof error.details === "object" ? error.details : {},
+      };
+    }
+    if (this.detail.code) {
+      const details = { ...this.detail };
+      delete details.code;
+      delete details.message;
+      return {
+        code: String(this.detail.code),
+        message: String(this.detail.message || this.detail.code),
+        details,
+      };
+    }
+    return null;
+  }
+
+  get errorCode() {
+    const p = this.errorPayload;
+    return p ? p.code : null;
+  }
+}
+
+class NotConfiguredError extends HomeCloudError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NotConfiguredError";
+  }
+}
+
+class NotLoggedInError extends HomeCloudError {
+  constructor(message, opts) {
+    super(message || "Not logged in. Run: homecloud login", opts);
+    this.name = "NotLoggedInError";
+  }
+}
+
+class ApiError extends HomeCloudError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ApiError";
+  }
+}
+
+class BadRequestError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "BadRequestError";
+  }
+}
+
+class UnauthorizedError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "UnauthorizedError";
+  }
+}
+
+class PermissionDeniedError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "PermissionDeniedError";
+  }
+}
+
+class NotFoundError extends ApiError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: 404, ...opts });
+    this.name = "NotFoundError";
+    this.resourceType = opts.resourceType || null;
+    this.resource = opts.resource || null;
+  }
+}
+
+class ConflictError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ConflictError";
+  }
+}
+
+class RateLimitError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "RateLimitError";
+  }
+}
+
+class ServiceUnavailableError extends ApiError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ServiceUnavailableError";
+  }
+}
+
+function detailMessage(detail) {
+  if (detail == null) return null;
+  if (typeof detail === "string" && detail.trim()) return detail.trim();
+  if (typeof detail === "object" && !Array.isArray(detail)) {
+    if (detail.error && typeof detail.error === "object") {
+      return String(detail.error.message || detail.error.code || "");
+    }
+    if (detail.message) return String(detail.message);
+    if (detail.code) return String(detail.code);
+  }
+  return null;
+}
+
+function errorFromStatus(statusCode, { detail = null, url = null } = {}) {
+  const apiMsg = detailMessage(detail);
+  if (statusCode === 400) return new BadRequestError(apiMsg || "Bad request", { statusCode, detail });
+  if (statusCode === 401) {
+    return new UnauthorizedError(apiMsg || "Unauthorized — check Access Key or console session", {
+      statusCode,
+      detail,
+    });
+  }
+  if (statusCode === 403) {
+    return new PermissionDeniedError(apiMsg || "Permission denied", { statusCode, detail });
+  }
+  if (statusCode === 404) {
+    return new NotFoundError(apiMsg || "Resource not found", { statusCode, detail });
+  }
+  if (statusCode === 409) return new ConflictError(apiMsg || "Conflict", { statusCode, detail });
+  if (statusCode === 429) {
+    return new RateLimitError(apiMsg || "Rate limit exceeded", { statusCode, detail });
+  }
+  if ([502, 503, 504].includes(statusCode)) {
+    return new ServiceUnavailableError(apiMsg || `Service unavailable (${statusCode})`, {
+      statusCode,
+      detail,
+    });
+  }
+  return new ApiError(apiMsg || `Request failed (${statusCode})`, { statusCode, detail });
+}
+
+module.exports = {
+  HomeCloudError,
+  NotConfiguredError,
+  NotLoggedInError,
+  ApiError,
+  BadRequestError,
+  UnauthorizedError,
+  PermissionDeniedError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  ServiceUnavailableError,
+  errorFromStatus,
+};

package/src/index.d.ts

@@ -1,35 +1,67 @@
-export type StsEntry = {
-  access_key_id: string;
-  secret_access_key: string;
-  session_token?: string;
-  base_url?: string;
-  mail_base_url?: string;
-  resource_type?: string;
-  resource_name?: string;
-};
-
-export declare class HomeCloudError extends Error {
-  statusCode?: number;
-  detail?: unknown;
-  constructor(message: string, opts?: { statusCode?: number; detail?: unknown });
-}
-
-export declare class HomeCloud {
-  so: {
-    upload(bucketName: string, filePath: string, opts?: { key?: string }): Promise<unknown>;
-    putJson(bucketName: string, objectKey: string, value: unknown): Promise<unknown>;
-  };
-  mq: {
-    send(queueName: string, body: unknown, opts?: { headers?: Record<string, string> }): Promise<unknown>;
-  };
-  secrets: {
-    get(secretName: string): Promise<unknown>;
-  };
-  mail: {
-    listMessages(opts?: { mailbox?: string; limit?: number }): Promise<unknown>;
-  };
-  static fromSts(sts: StsEntry, opts?: { accountId?: string; apex?: string }): HomeCloud;
-  static fromFunctionContext(context: Record<string, unknown>, opts: { binding: string }): HomeCloud;
-}
-
-export declare const DEFAULT_APEX: string;
+export type StsEntry = {
+  access_key_id: string;
+  secret_access_key: string;
+  session_token?: string;
+  base_url?: string;
+  mail_base_url?: string;
+  resource_type?: string;
+  resource_name?: string;
+};
+
+export declare class HomeCloudError extends Error {
+  statusCode?: number | null;
+  detail?: unknown;
+  constructor(message: string, opts?: { statusCode?: number | null; detail?: unknown });
+}
+
+export declare class NotConfiguredError extends HomeCloudError {}
+export declare class NotLoggedInError extends HomeCloudError {}
+export declare class ApiError extends HomeCloudError {}
+export declare class BadRequestError extends ApiError {}
+export declare class UnauthorizedError extends ApiError {}
+export declare class PermissionDeniedError extends ApiError {}
+export declare class NotFoundError extends ApiError {
+  resourceType?: string | null;
+  resource?: string | null;
+}
+export declare class ConflictError extends ApiError {}
+export declare class RateLimitError extends ApiError {}
+export declare class ServiceUnavailableError extends ApiError {}
+
+export declare class HomeCloud {
+  so: any;
+  storage: any;
+  mq: any;
+  secrets: any;
+  mail: any;
+  accounts: any;
+  apps: any;
+  queues: any;
+  functions: any;
+  accountId: string | null;
+  accessToken: string | null;
+  constructor(opts?: Record<string, unknown>);
+  static fromEnv(opts?: Record<string, unknown>): HomeCloud;
+  static fromProfile(profile?: string | null, opts?: Record<string, unknown>): HomeCloud;
+  static fromCredentials(
+    accessKeyId: string,
+    secretAccessKey: string,
+    opts?: Record<string, unknown>
+  ): HomeCloud;
+  static fromSts(sts: StsEntry, opts?: { accountId?: string; apex?: string }): HomeCloud;
+  static fromFunctionContext(
+    context: Record<string, unknown>,
+    opts: { binding: string }
+  ): HomeCloud;
+  ensureAccountId(): Promise<string>;
+  login(username: string, password: string, opts?: { mfaCode?: string }): Promise<void>;
+  loginBrowser(opts?: {
+    openBrowser?: boolean;
+    onWaiting?: (uri: string) => void;
+    mfaToken?: string;
+  }): Promise<void>;
+}
+
+export declare const AsyncHomeCloud: typeof HomeCloud;
+export declare const DEFAULT_APEX: string;
+export declare function signRequestHeaders(opts: Record<string, unknown>): Record<string, string>;