@miosa/sdk 0.3.0

package/src/resources/admin.ts

@@ -0,0 +1,348 @@
+import type { HttpClient } from "../http.js";
+
+type Json = Record<string, unknown>;
+type Query = Record<string, string | number | boolean | undefined>;
+
+function withDefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined && v !== null) out[k] = v;
+  }
+  return out as Partial<T>;
+}
+
+export interface ListAdminUsersParams {
+  limit?: number;
+  cursor?: string;
+  q?: string;
+  status?: "active" | "suspended" | "deleted";
+}
+
+export interface ListAdminTenantsParams {
+  limit?: number;
+  cursor?: string;
+  q?: string;
+}
+
+export interface ListAdminComputersParams {
+  limit?: number;
+  cursor?: string;
+  status?:
+    | "creating"
+    | "provisioning"
+    | "running"
+    | "stopped"
+    | "paused"
+    | "error";
+  tenantId?: string;
+}
+
+export interface ListAdminApiKeysParams {
+  limit?: number;
+  cursor?: string;
+  tenantId?: string;
+  status?: "active" | "revoked" | "expired";
+}
+
+export interface CreateAdminApiKeyParams {
+  name: string;
+  tenantId: string;
+  userId: string;
+  keyType?: "user" | "admin" | "platform";
+  purpose?: "api" | "optimal";
+  rateLimitRpm?: number;
+  expiresAt?: string;
+  allowedIps?: string[];
+}
+
+export interface BulkUserActionParams {
+  userIds: string[];
+  action: "suspend" | "unsuspend" | "delete" | "tag" | "notify";
+  params?: Json;
+}
+
+/**
+ * Admin surface — `/api/v1/admin/*` endpoints.
+ *
+ * Requires a `msk_a_*` or `msk_p_*` API key, or an admin JWT. Calls from
+ * a user-role credential return 403 Forbidden.
+ */
+export class Admin {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /** Escape hatch — call any admin endpoint by method + path. */
+  async request<T = Json>(
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+    path: string,
+    body?: unknown,
+    query?: Query,
+  ): Promise<T> {
+    const fullPath = query
+      ? (() => {
+          const qs = new URLSearchParams();
+          for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined) qs.set(k, String(v));
+          }
+          const s = qs.toString();
+          return s ? `${path}?${s}` : path;
+        })()
+      : path;
+    // Route via the low-level method helpers so retries/backoff still apply.
+    switch (method) {
+      case "GET":
+        return this.http.get<T>(fullPath);
+      case "POST":
+        return this.http.post<T>(fullPath, body);
+      case "PUT":
+        return this.http.put<T>(fullPath, body);
+      case "PATCH":
+        return this.http.patch<T>(fullPath, body);
+      case "DELETE":
+        return this.http.delete<T>(fullPath, body);
+    }
+  }
+
+  // ── Overview ────────────────────────────────────────────────
+
+  dashboard(): Promise<Json> {
+    return this.http.get("/admin/dashboard");
+  }
+  stats(): Promise<Json> {
+    return this.http.get("/admin/stats");
+  }
+  auditLog(params?: { limit?: number; cursor?: string }): Promise<Json> {
+    return this.http.get("/admin/audit-log", {
+      limit: params?.limit,
+      cursor: params?.cursor,
+    });
+  }
+  detailedHealth(): Promise<Json> {
+    return this.http.get("/admin/health/detailed");
+  }
+
+  // ── Credits ─────────────────────────────────────────────────
+
+  grantCredits(params: {
+    tenantId: string;
+    amount: number;
+    description: string;
+    expiresAt?: string;
+  }): Promise<Json> {
+    return this.http.post(
+      "/admin/credits/grant",
+      withDefined({
+        tenant_id: params.tenantId,
+        amount: params.amount,
+        description: params.description,
+        expires_at: params.expiresAt,
+      }),
+    );
+  }
+  deductCredits(params: {
+    tenantId: string;
+    amount: number;
+    description: string;
+  }): Promise<Json> {
+    return this.http.post("/admin/credits/deduct", {
+      tenant_id: params.tenantId,
+      amount: params.amount,
+      description: params.description,
+    });
+  }
+  refundCredits(params: {
+    tenantId: string;
+    amount: number;
+    description: string;
+    transactionId?: string;
+  }): Promise<Json> {
+    return this.http.post(
+      "/admin/credits/refund",
+      withDefined({
+        tenant_id: params.tenantId,
+        amount: params.amount,
+        description: params.description,
+        transaction_id: params.transactionId,
+      }),
+    );
+  }
+  tenantBalance(tenantId: string): Promise<Json> {
+    return this.http.get(`/admin/credits/${tenantId}/balance`);
+  }
+  tenantCreditHistory(
+    tenantId: string,
+    params?: { limit?: number; cursor?: string },
+  ): Promise<Json> {
+    return this.http.get(`/admin/credits/${tenantId}/history`, {
+      limit: params?.limit,
+      cursor: params?.cursor,
+    });
+  }
+
+  // ── Users ───────────────────────────────────────────────────
+
+  listUsers(params?: ListAdminUsersParams): Promise<Json> {
+    return this.http.get("/admin/users", {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      q: params?.q,
+      status: params?.status,
+    });
+  }
+  getUser(userId: string): Promise<Json> {
+    return this.http.get(`/admin/users/${userId}`);
+  }
+  updateUser(userId: string, attrs: Json): Promise<Json> {
+    return this.http.put(`/admin/users/${userId}`, attrs);
+  }
+  deleteUser(userId: string): Promise<Json> {
+    return this.http.delete(`/admin/users/${userId}`);
+  }
+  changeUserRole(
+    userId: string,
+    role: "user" | "admin" | "owner" | "super_admin",
+  ): Promise<Json> {
+    return this.http.post(`/admin/users/${userId}/role`, { role });
+  }
+  forceLogout(userId: string): Promise<Json> {
+    return this.http.post(`/admin/users/${userId}/force-logout`);
+  }
+  suspendUser(userId: string, reason?: string): Promise<Json> {
+    return this.http.post(
+      `/admin/users/${userId}/suspend`,
+      reason ? { reason } : undefined,
+    );
+  }
+  unsuspendUser(userId: string): Promise<Json> {
+    return this.http.post(`/admin/users/${userId}/unsuspend`);
+  }
+  banUser(userId: string, reason: string, expiresAt?: string): Promise<Json> {
+    return this.http.post(
+      `/admin/users/${userId}/ban`,
+      withDefined({ reason, expires_at: expiresAt }),
+    );
+  }
+  unbanUser(userId: string): Promise<Json> {
+    return this.http.post(`/admin/users/${userId}/unban`);
+  }
+  bulkUserAction(params: BulkUserActionParams): Promise<Json> {
+    return this.http.post(
+      "/admin/users/bulk",
+      withDefined({
+        user_ids: params.userIds,
+        action: params.action,
+        params: params.params,
+      }),
+    );
+  }
+
+  // ── Tenants ─────────────────────────────────────────────────
+
+  listTenants(params?: ListAdminTenantsParams): Promise<Json> {
+    return this.http.get("/admin/tenants", {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      q: params?.q,
+    });
+  }
+  tenantDetail(tenantId: string): Promise<Json> {
+    return this.http.get(`/admin/tenants/${tenantId}/detail`);
+  }
+  suspendTenant(tenantId: string, reason?: string): Promise<Json> {
+    return this.http.post(
+      `/admin/tenants/${tenantId}/suspend`,
+      reason ? { reason } : undefined,
+    );
+  }
+  unsuspendTenant(tenantId: string): Promise<Json> {
+    return this.http.post(`/admin/tenants/${tenantId}/unsuspend`);
+  }
+  changeTenantPlan(
+    tenantId: string,
+    plan: "free" | "starter" | "pro" | "scale",
+    prorate = true,
+  ): Promise<Json> {
+    return this.http.post(`/admin/tenants/${tenantId}/plan`, { plan, prorate });
+  }
+  deleteTenant(tenantId: string): Promise<Json> {
+    return this.http.delete(`/admin/tenants/${tenantId}`);
+  }
+
+  // ── Computers ───────────────────────────────────────────────
+
+  listComputers(params?: ListAdminComputersParams): Promise<Json> {
+    return this.http.get("/admin/computers", {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      status: params?.status,
+      tenant_id: params?.tenantId,
+    });
+  }
+  deleteComputer(computerId: string): Promise<Json> {
+    return this.http.delete(`/admin/computers/${computerId}`);
+  }
+  suspendComputer(computerId: string): Promise<Json> {
+    return this.http.post(`/admin/computers/${computerId}/suspend`);
+  }
+  resumeComputer(computerId: string): Promise<Json> {
+    return this.http.post(`/admin/computers/${computerId}/resume`);
+  }
+  restartComputer(computerId: string): Promise<Json> {
+    return this.http.post(`/admin/computers/${computerId}/restart`);
+  }
+  purgeStaleComputers(): Promise<Json> {
+    return this.http.post("/admin/computers/purge-stale");
+  }
+
+  // ── API Keys ────────────────────────────────────────────────
+
+  listApiKeys(params?: ListAdminApiKeysParams): Promise<Json> {
+    return this.http.get("/admin/api-keys", {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      tenant_id: params?.tenantId,
+      status: params?.status,
+    });
+  }
+  createApiKey(params: CreateAdminApiKeyParams): Promise<Json> {
+    return this.http.post(
+      "/admin/api-keys",
+      withDefined({
+        name: params.name,
+        tenant_id: params.tenantId,
+        user_id: params.userId,
+        key_type: params.keyType ?? "user",
+        purpose: params.purpose ?? "api",
+        rate_limit_rpm: params.rateLimitRpm,
+        expires_at: params.expiresAt,
+        allowed_ips: params.allowedIps,
+      }),
+    );
+  }
+  apiKeyStats(): Promise<Json> {
+    return this.http.get("/admin/api-keys/stats");
+  }
+  bulkRevokeApiKeys(keyIds: string[]): Promise<Json> {
+    return this.http.post("/admin/api-keys/bulk-revoke", { key_ids: keyIds });
+  }
+  revokeApiKey(keyId: string): Promise<Json> {
+    return this.http.delete(`/admin/api-keys/${keyId}`);
+  }
+
+  // ── Optimal ─────────────────────────────────────────────────
+
+  optimalStatus(): Promise<Json> {
+    return this.http.get("/admin/optimal/status");
+  }
+  listOptimalModels(): Promise<Json> {
+    return this.http.get("/admin/optimal/models");
+  }
+  switchOptimalModel(modelId: string): Promise<Json> {
+    return this.http.post("/admin/optimal/models/switch", {
+      model_id: modelId,
+    });
+  }
+}

package/src/resources/analytics.ts

@@ -0,0 +1,60 @@
+/**
+ * Analytics — overview + timeseries (admin scope).
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface AnalyticsFilters {
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface TimeseriesParams extends AnalyticsFilters {
+  metric?: string;
+  period?: string;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "analytics", "series", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, string | number | boolean | undefined> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  ) as Record<string, string | number | boolean | undefined>;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class Analytics {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get the platform analytics overview. */
+  async overview(
+    filters: AnalyticsFilters = {},
+  ): Promise<Record<string, unknown>> {
+    const query = stripUndefined(filters as Record<string, unknown>);
+    const data = await this.http.get<unknown>("/analytics/overview", query);
+    return unwrap<Record<string, unknown>>(data);
+  }
+
+  /** Get a timeseries for a metric over a period. */
+  async timeseries(
+    params: TimeseriesParams = {},
+  ): Promise<Record<string, unknown>> {
+    const query = stripUndefined(params as Record<string, unknown>);
+    const data = await this.http.get<unknown>("/analytics/timeseries", query);
+    return unwrap<Record<string, unknown>>(data);
+  }
+}

package/src/resources/api-keys.ts

@@ -0,0 +1,119 @@
+/**
+ * ApiKeys resource — programmatic API key management.
+ *
+ * The plaintext key is returned ONLY at create time. Store it immediately;
+ * the server only keeps a hash.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { HttpClient } from "../http.js";
+
+// ── Branded IDs ──────────────────────────────────────────────────────────────
+
+export type ApiKeyId = string & { readonly __brand: "ApiKeyId" };
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface ApiKeyData {
+  id: ApiKeyId;
+  tenant_id: string;
+  name: string;
+  prefix?: string;
+  scopes?: string[];
+  expires_at?: string | null;
+  last_used_at?: string | null;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export interface ApiKeyCreateResult extends ApiKeyData {
+  /** One-time plaintext key. Store immediately. */
+  token?: string;
+  key?: string;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface ApiKeyListParams {
+  limit?: number;
+  cursor?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface ApiKeyCreateParams {
+  name: string;
+  scopes?: string[];
+  expires_at?: string;
+  expiresAt?: string;
+  idempotencyKey?: 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", "keys", "api_keys", "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 [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+function idempotencyKey(key?: string): string {
+  return key ?? randomUUID();
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class ApiKeys {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(params: ApiKeyListParams = {}): Promise<ApiKeyData[]> {
+    const query = stripUndefined({ ...params }) as Record<
+      string,
+      string | number | boolean | undefined
+    >;
+    const data = await this.http.get<unknown>("/api-keys", query);
+    return listItems<ApiKeyData>(data);
+  }
+
+  async create(params: ApiKeyCreateParams): Promise<ApiKeyCreateResult> {
+    const { idempotencyKey: ikey, expiresAt, ...rest } = params;
+    const body = stripUndefined({
+      ...rest,
+      expires_at: expiresAt ?? rest.expires_at,
+    });
+    const data = await this.http.request<unknown>("/api-keys", {
+      method: "POST",
+      body,
+      headers: { "Idempotency-Key": idempotencyKey(ikey) },
+    });
+    return unwrap<ApiKeyCreateResult>(data);
+  }
+
+  async delete(keyId: string): Promise<void> {
+    await this.http.delete<unknown>(`/api-keys/${keyId}`);
+  }
+}

package/src/resources/audit-log.ts

@@ -0,0 +1,64 @@
+/**
+ * Audit log — admin-scoped event history.
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface AuditLogEvent {
+  id?: string;
+  action?: string;
+  actor_id?: string;
+  resource_type?: string;
+  resource_id?: string;
+  metadata?: Record<string, unknown>;
+  inserted_at?: string;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface AuditLogListParams {
+  action?: string;
+  actor_id?: string;
+  resource_type?: string;
+  limit?: number;
+  cursor?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "audit_log", "events", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, string | number | boolean | undefined> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  ) as Record<string, string | number | boolean | undefined>;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class AuditLog {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List audit-log events with optional filters. */
+  async list(params: AuditLogListParams = {}): Promise<AuditLogEvent[]> {
+    const query = stripUndefined(params as Record<string, unknown>);
+    const data = await this.http.get<unknown>("/audit-log", query);
+    const result = unwrap<AuditLogEvent[] | unknown>(data);
+    if (Array.isArray(result)) return result;
+    return [];
+  }
+}

package/src/resources/benchmarks.ts

@@ -0,0 +1,104 @@
+/**
+ * Benchmarks — admin-triggered platform benchmark runs.
+ *
+ * Routes: /admin/benchmarks/*
+ * Requires admin credential (msk_a_* / msk_p_* or admin JWT).
+ * Available kinds: cold_boot, fleet_routing, concurrent_create, full_e2e.
+ */
+
+import type { HttpClient } from "../http.js";
+
+export interface BenchmarkCreateParams {
+  kind: string;
+  [key: string]: unknown;
+}
+
+export interface BenchmarkCompareParams {
+  left_id: string;
+  right_id: string;
+  [key: string]: unknown;
+}
+
+function unwrap(data: unknown): Record<string, unknown> {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "benchmarks", "samples", "items"]) {
+      if (k in d) return d[k] as Record<string, unknown>;
+    }
+  }
+  return data as Record<string, unknown>;
+}
+
+function unwrapList(data: unknown): Record<string, unknown>[] {
+  if (Array.isArray(data)) return data as Record<string, unknown>[];
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    for (const k of ["data", "benchmarks", "samples", "items"]) {
+      if (Array.isArray(d[k])) return d[k] as Record<string, unknown>[];
+    }
+  }
+  return [];
+}
+
+export class Benchmarks {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(
+    filters: Record<string, string | number | boolean | undefined> = {},
+  ): Promise<Record<string, unknown>[]> {
+    const query = Object.fromEntries(
+      Object.entries(filters).filter(([, v]) => v !== undefined),
+    ) as Record<string, string | number | boolean | undefined>;
+    const data = await this.http.get<unknown>("/admin/benchmarks", query);
+    return unwrapList(data);
+  }
+
+  async get(benchmarkId: string): Promise<Record<string, unknown>> {
+    return unwrap(
+      await this.http.get<unknown>(`/admin/benchmarks/${benchmarkId}`),
+    );
+  }
+
+  /** Start a new benchmark run — pass kind and run-specific options. */
+  async create(
+    params: BenchmarkCreateParams,
+  ): Promise<Record<string, unknown>> {
+    const body = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v !== undefined),
+    );
+    return unwrap(await this.http.post<unknown>("/admin/benchmarks", body));
+  }
+
+  async cancel(benchmarkId: string): Promise<Record<string, unknown>> {
+    return unwrap(
+      await this.http.post<unknown>(`/admin/benchmarks/${benchmarkId}/cancel`),
+    );
+  }
+
+  /** Return per-iteration timing samples for a benchmark run. */
+  async samples(
+    benchmarkId: string,
+    filters: Record<string, string | number | boolean | undefined> = {},
+  ): Promise<Record<string, unknown>[]> {
+    const query = Object.fromEntries(
+      Object.entries(filters).filter(([, v]) => v !== undefined),
+    ) as Record<string, string | number | boolean | undefined>;
+    const data = await this.http.get<unknown>(
+      `/admin/benchmarks/${benchmarkId}/samples`,
+      query,
+    );
+    return unwrapList(data);
+  }
+
+  /** Compare two benchmark runs. */
+  async compare(
+    params: BenchmarkCompareParams,
+  ): Promise<Record<string, unknown>> {
+    const body = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v !== undefined),
+    );
+    return unwrap(
+      await this.http.post<unknown>("/admin/benchmarks/compare", body),
+    );
+  }
+}