@miosa/sdk 1.2.1 → 1.2.3

package/src/resources/tenant.ts

@@ -14,26 +14,135 @@ export interface TenantPlan {
   [key: string]: unknown;
 }
 
+export interface PreviewDomainData {
+  preview_domain?: string | null;
+  default_domain?: string;
+  status?: string;
+  dns_status?: string;
+  cname_target?: string | null;
+  dns_instructions?: unknown;
+  [key: string]: unknown;
+}
+
+export interface TenantBrandingUpdateParams {
+  product_name?: string;
+  logo_url?: string;
+  support_url?: string;
+  support_email?: string;
+  primary_color?: string;
+  background_color?: string;
+  [key: string]: unknown;
+}
+
+export type BrandingData = TenantBrandingUpdateParams;
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function unwrap<T>(payload: unknown): T {
   if (payload && typeof payload === "object") {
     const p = payload as Record<string, unknown>;
-    for (const k of ["data", "tenant", "items"]) {
+    for (const k of ["data", "tenant", "branding", "items"]) {
       if (k in p) return p[k] as T;
     }
   }
   return payload as T;
 }
 
+// ── Sub-resources ────────────────────────────────────────────────────────────
+
+class PreviewDomain {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get the tenant's white-label preview domain settings. */
+  async get(): Promise<PreviewDomainData> {
+    const data = await this.http.get<unknown>("/tenant/preview-domain");
+    return unwrap<PreviewDomainData>(data);
+  }
+
+  /** Set the tenant's white-label preview domain. */
+  async set(domain: string): Promise<PreviewDomainData> {
+    const data = await this.http.put<unknown>("/tenant/preview-domain", {
+      preview_domain: domain,
+    });
+    return unwrap<PreviewDomainData>(data);
+  }
+
+  /** Re-run DNS verification for the configured preview domain. */
+  async verify(): Promise<PreviewDomainData> {
+    const data = await this.http.post<unknown>(
+      "/tenant/preview-domain/verify",
+      {},
+    );
+    return unwrap<PreviewDomainData>(data);
+  }
+
+  /** Remove the tenant's custom preview domain. */
+  async delete(): Promise<void> {
+    await this.http.delete<unknown>("/tenant/preview-domain");
+  }
+}
+
+class Branding {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get tenant branding used by white-label hosted surfaces. */
+  async get(): Promise<BrandingData> {
+    const data = await this.http.get<unknown>("/tenant/branding");
+    return unwrap<BrandingData>(data);
+  }
+
+  /** Update tenant branding used by white-label hosted surfaces. */
+  async set(params: TenantBrandingUpdateParams): Promise<BrandingData> {
+    const body = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v !== undefined),
+    );
+    const data = await this.http.put<unknown>("/tenant/branding", {
+      branding: body,
+    });
+    return unwrap<BrandingData>(data);
+  }
+
+  /** Reset tenant branding to platform defaults. */
+  async delete(): Promise<void> {
+    await this.http.delete<unknown>("/tenant/branding");
+  }
+}
+
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Tenant {
-  constructor(private readonly http: HttpClient) {}
+  private readonly http: HttpClient;
+  readonly preview_domain: PreviewDomain;
+  readonly branding: Branding;
+
+  /** camelCase alias for SDK consumers that avoid snake_case properties. */
+  readonly previewDomain: PreviewDomain;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+    this.preview_domain = new PreviewDomain(http);
+    this.previewDomain = this.preview_domain;
+    this.branding = new Branding(http);
+  }
 
   /** Get the current tenant's plan, limits, and live usage counters. */
   async current(): Promise<TenantPlan> {
     const data = await this.http.get<unknown>("/tenant/plan");
     return unwrap<TenantPlan>(data);
   }
+
+  /** Convenience alias for `tenant.branding.get()`. */
+  async getBranding(): Promise<BrandingData> {
+    return this.branding.get();
+  }
+
+  /** Convenience alias for `tenant.branding.set(...)`. */
+  async setBranding(params: TenantBrandingUpdateParams): Promise<BrandingData> {
+    return this.branding.set(params);
+  }
+
+  /** Convenience alias for `tenant.branding.delete()`. */
+  async deleteBranding(): Promise<void> {
+    await this.branding.delete();
+  }
 }

package/src/resources/webhooks.ts

@@ -2,7 +2,7 @@
  * Webhooks resource — tenant outgoing event delivery.
  */
 
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 
 import type { HttpClient } from "../http.js";
 
@@ -101,11 +101,64 @@ function idempotencyKey(key?: string): string {
   return key ?? randomUUID();
 }
 
+function bodyBuffer(body: Buffer | Uint8Array | string): Buffer {
+  if (Buffer.isBuffer(body)) return body;
+  if (typeof body === "string") return Buffer.from(body, "utf8");
+  return Buffer.from(body);
+}
+
+/**
+ * Verify the `Miosa-Signature` webhook header.
+ *
+ * Header format: `t=<unix_seconds>,v1=<hex_hmac>`.
+ * Signed payload: `<timestamp>.<raw_body>`.
+ */
+export function verifySignature(
+  body: Buffer | Uint8Array | string,
+  header: string,
+  secret: string,
+  toleranceSec = 300,
+): boolean {
+  const parts = Object.fromEntries(
+    header
+      .split(",")
+      .map((chunk) => chunk.split("=", 2))
+      .filter(([key, value]) => key && value),
+  );
+
+  const timestamp = parts.t;
+  const received = parts.v1;
+  if (!timestamp || !received || !secret) return false;
+
+  const unixSeconds = Number(timestamp);
+  if (!Number.isFinite(unixSeconds)) return false;
+
+  const ageSec = Math.abs(Date.now() / 1000 - unixSeconds);
+  if (ageSec > toleranceSec) {
+    throw new Error("webhook timestamp too old");
+  }
+
+  const rawBody = bodyBuffer(body);
+  const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
+  const expected = createHmac("sha256", secret).update(signed).digest("hex");
+
+  try {
+    return timingSafeEqual(
+      Buffer.from(expected, "utf8"),
+      Buffer.from(received, "utf8"),
+    );
+  } catch {
+    return false;
+  }
+}
+
 // ── Main resource ─────────────────────────────────────────────────────────────
 
 export class Webhooks {
   constructor(private readonly http: HttpClient) {}
 
+  static verifySignature = verifySignature;
+
   async list(params: WebhookListParams = {}): Promise<WebhookData[]> {
     const query = stripUndefined({ ...params }) as Record<
       string,

package/src/resources/workspaces.ts

@@ -0,0 +1,285 @@
+/**
+ * Workspaces resource — top-level tenant workspaces grouping computers.
+ *
+ * A workspace is a logical bucket of computers (handy for teams / projects).
+ * Accessed via `miosa.workspaces` on the top-level client.
+ *
+ * @example
+ * ```ts
+ * const ws = await miosa.workspaces.create({ name: "prod" });
+ * const computers = await miosa.workspaces.listComputers(ws.id);
+ * ```
+ */
+
+import type { HttpClient } from "../http.js";
+import type { ComputerData } from "../types.js";
+import { Computer } from "./computer.js";
+
+// ── Branded IDs ──────────────────────────────────────────────────────────────
+
+export type WorkspaceId = string & { readonly __brand: "WorkspaceId" };
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface WorkspaceData {
+  id: WorkspaceId;
+  tenant_id: string;
+  name: string;
+  slug?: string | null;
+  description?: string | null;
+  metadata?: Record<string, unknown> | null;
+  settings?: Record<string, unknown> | null;
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface WorkspaceCreateParams {
+  name: string;
+  slug?: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WorkspaceUpdateParams {
+  name?: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WorkspaceComputerTemplateCreateParams {
+  name: string;
+  templateType?: string;
+  template_type?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object" && "data" in (payload as object)) {
+    return (payload as { data: T }).data;
+  }
+  return payload as T;
+}
+
+function listItems<T>(
+  payload: unknown,
+  candidateKeys: string[] = ["data", "items"],
+): T[] {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== "object") return [];
+  const p = payload as Record<string, unknown>;
+  if (Array.isArray(p.data)) return p.data as T[];
+  for (const key of candidateKeys) {
+    if (Array.isArray(p[key])) return p[key] as T[];
+  }
+  return [];
+}
+
+// ── Workspaces resource ───────────────────────────────────────────────────────
+
+export class Workspaces {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Create a new workspace.
+   */
+  async create(params: WorkspaceCreateParams): Promise<WorkspaceData> {
+    const payload = await this.http.post<unknown>("/workspaces", params);
+    return unwrap<WorkspaceData>(payload);
+  }
+
+  /**
+   * List all workspaces visible to the current credential.
+   */
+  async list(): Promise<WorkspaceData[]> {
+    const payload = await this.http.get<unknown>("/workspaces");
+    if (
+      payload &&
+      typeof payload === "object" &&
+      "workspaces" in (payload as object)
+    ) {
+      const p = payload as Record<string, unknown>;
+      return (p["workspaces"] as WorkspaceData[]) ?? [];
+    }
+    return listItems<WorkspaceData>(payload, ["data", "workspaces", "items"]);
+  }
+
+  /**
+   * Get a single workspace by ID.
+   */
+  async get(id: WorkspaceId | string): Promise<WorkspaceData> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}`);
+    return unwrap<WorkspaceData>(payload);
+  }
+
+  /**
+   * Update a workspace's metadata.
+   */
+  async update(
+    id: WorkspaceId | string,
+    params: WorkspaceUpdateParams,
+  ): Promise<WorkspaceData> {
+    const payload = await this.http.patch<unknown>(`/workspaces/${id}`, params);
+    return unwrap<WorkspaceData>(payload);
+  }
+
+  /**
+   * Delete a workspace. Does not delete member computers.
+   */
+  async delete(id: WorkspaceId | string): Promise<void> {
+    await this.http.delete<void>(`/workspaces/${id}`);
+  }
+
+  /**
+   * Update workspace-level settings.
+   */
+  async updateSettings(
+    id: WorkspaceId | string,
+    settings: Record<string, unknown>,
+  ): Promise<WorkspaceData> {
+    const payload = await this.http.put<unknown>(
+      `/workspaces/${id}/settings`,
+      settings,
+    );
+    return unwrap<WorkspaceData>(payload);
+  }
+
+  /**
+   * List all computers that belong to the given workspace.
+   */
+  async listComputers(id: WorkspaceId | string): Promise<Computer[]> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/computers`);
+    const items = listItems<ComputerData>(payload, [
+      "data",
+      "computers",
+      "items",
+    ]);
+    return items.map((d) => new Computer(this.http, d));
+  }
+
+  /**
+   * List all sandboxes that belong to this workspace.
+   */
+  async listSandboxes(
+    id: WorkspaceId | string,
+  ): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/sandboxes`);
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "sandboxes",
+      "items",
+    ]);
+  }
+
+  /**
+   * List all deployments that belong to this workspace.
+   */
+  async listDeployments(
+    id: WorkspaceId | string,
+  ): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(
+      `/workspaces/${id}/deployments`,
+    );
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "deployments",
+      "items",
+    ]);
+  }
+
+  /**
+   * List all managed databases that belong to this workspace.
+   */
+  async listDatabases(
+    id: WorkspaceId | string,
+  ): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/databases`);
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "databases",
+      "items",
+    ]);
+  }
+
+  /**
+   * List all projects that belong to this workspace.
+   */
+  async listProjects(
+    id: WorkspaceId | string,
+  ): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/projects`);
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "projects",
+      "items",
+    ]);
+  }
+
+  /**
+   * Return aggregate resource stats for this workspace.
+   */
+  async stats(id: WorkspaceId | string): Promise<Record<string, unknown>> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/stats`);
+    return unwrap<Record<string, unknown>>(payload);
+  }
+
+  /**
+   * Return metered usage data for this workspace.
+   */
+  async usage(id: WorkspaceId | string): Promise<Record<string, unknown>> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/usage`);
+    return unwrap<Record<string, unknown>>(payload);
+  }
+
+  /**
+   * Return activity feed for this workspace.
+   */
+  async activity(id: WorkspaceId | string): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(`/workspaces/${id}/activity`);
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "activity",
+      "events",
+      "items",
+    ]);
+  }
+
+  /**
+   * List computer templates available in this workspace.
+   */
+  async listComputerTemplates(
+    id: WorkspaceId | string,
+  ): Promise<Record<string, unknown>[]> {
+    const payload = await this.http.get<unknown>(
+      `/workspaces/${id}/computer-templates`,
+    );
+    return listItems<Record<string, unknown>>(payload, [
+      "data",
+      "templates",
+      "items",
+    ]);
+  }
+
+  /**
+   * Create a computer template scoped to this workspace.
+   */
+  async createComputerTemplate(
+    id: WorkspaceId | string,
+    params: WorkspaceComputerTemplateCreateParams,
+  ): Promise<Record<string, unknown>> {
+    const payload = await this.http.post<unknown>(
+      `/workspaces/${id}/computer-templates`,
+      params,
+    );
+    return unwrap<Record<string, unknown>>(payload);
+  }
+}

package/src/types.ts

@@ -78,9 +78,9 @@ export interface ComputerData {
   id: ComputerId;
   name: string;
   /**
-   * URL-safe identifier used in preview URLs:
-   * `https://{port}-{slug}.sandbox.{preview_domain}`.
-   * Falls back to the computer id when no slug is assigned.
+   * URL-safe identifier used in preview URLs: `https://{port}-{slug}.sandbox.{preview_domain}`.
+   * Falls back to the computer id when no slug is assigned. The domain is the
+   * tenant's white-label `preview_domain` (server-provided) — never hardcode it.
    */
   slug: string;
   status: ComputerStatus;
@@ -91,9 +91,9 @@ export interface ComputerData {
   metadata: Record<string, string>;
   /** Controls who can access the HTTP preview URL. Defaults to `"public"`. */
   visibility: ComputerVisibility;
-  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>`. */
+  /** Public ingress root, e.g. `https://<slug>.sandbox.<preview_domain>` (server-provided). */
   sandbox_url?: string;
-  /** Tenant's white-label preview/base domain, e.g. `cliniciq.com`. */
+  /** Tenant's white-label preview/base domain (e.g. `cliniciq.com`). Use to build preview URLs. */
   preview_domain?: string;
   /** KasmVNC URL for desktop templates. */
   desktop_url?: string;