@ninedeploy/sdk 0.10.6 → 0.16.0

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@ninedeploy/sdk",
-  "version": "0.10.6",
+  "version": "0.16.0",
   "description": "Official TypeScript SDK for NineDeploy PaaS",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/NineDeploy/NineDeploy.git",
+    "url": "git+https://github.com/ninedeploy/ninedeploy.git",
     "directory": "packages/sdk"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@ninedeploy/schemas": "0.10.6",
+    "@ninedeploy/schemas": "0.16.0",
     "js-yaml": "^4.3.1"
   },
   "devDependencies": {

package/src/apiPath.ts

@@ -0,0 +1,23 @@
+// Validated GET paths for `client.api.get` (0.15 T4).
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import { NineDeployError } from './errors.js';
+
+// ── 0.15 T4 api ──
+/** Query parameters for `client.api.get`. */
+export type ApiQuery = Record<string, string | number | boolean | undefined>;
+
+/** The paths `client.api.get` accepts: under `/v1/`, plain segments, no `..`. */
+const API_PATH = /^\/v1\/[A-Za-z0-9/_.-]+$/;
+
+/** Validate an `api.get` path and append its query string. Exported for tests. */
+export function apiGetUrl(path: string, query?: ApiQuery): string {
+  if (!API_PATH.test(path) || path.split('/').includes('..')) {
+    throw new NineDeployError(0, 'invalid_path', `Not an API path: ${path}`);
+  }
+  const qs = Object.entries(query ?? {})
+    .filter((entry): entry is [string, string | number | boolean] => entry[1] !== undefined)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+    .join('&');
+  return qs ? `${path}?${qs}` : path;
+}

package/src/client.ts

@@ -0,0 +1,70 @@
+// The NineDeployClient surface, composed from the per-resource modules.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import { createTransport, type NineDeployClientOptions } from './transport.js';
+import { authApi, type AuthApi } from './resources/auth.js';
+import { servicesApi, type ServicesApi } from './resources/services.js';
+import { deploysApi, type DeploysApi } from './resources/deploys.js';
+import { envApi, type EnvApi } from './resources/env.js';
+import { domainsApi, type DomainsApi } from './resources/domains.js';
+import { networkApi, type NetworkApi } from './resources/network.js';
+import { traefikApi, type TraefikApi } from './resources/traefik.js';
+import { databasesApi, type DatabasesApi } from './resources/databases.js';
+import { volumesApi, type VolumesApi } from './resources/volumes.js';
+import { sourcesApi, type SourcesApi } from './resources/sources.js';
+import { serversApi, type ServersApi } from './resources/servers.js';
+import { templatesApi, type TemplatesApi } from './resources/templates.js';
+import { settingsApi, type SettingsApi } from './resources/settings.js';
+import { systemApi, type SystemApi } from './resources/system.js';
+import { pluginsApi, type PluginsApi } from './resources/plugins.js';
+import { logsApi, type LogsApi } from './resources/logs.js';
+import { terminalsApi, type TerminalsApi } from './resources/terminals.js';
+
+export interface NineDeployClient
+  extends AuthApi,
+    ServicesApi,
+    DeploysApi,
+    EnvApi,
+    DomainsApi,
+    NetworkApi,
+    TraefikApi,
+    DatabasesApi,
+    VolumesApi,
+    SourcesApi,
+    ServersApi,
+    TemplatesApi,
+    SettingsApi,
+    SystemApi,
+    PluginsApi,
+    LogsApi,
+    TerminalsApi {}
+
+/**
+ * Create a typed NineDeploy API client. Used by both the web dashboard and the CLI.
+ *
+ * @example
+ * const client = createClient({ baseUrl: 'http://localhost:3000', getToken: () => token });
+ * const services = await client.services.list();
+ */
+export function createClient(opts: NineDeployClientOptions): NineDeployClient {
+  const t = createTransport(opts);
+  return {
+    ...authApi(t),
+    ...servicesApi(t),
+    ...deploysApi(t),
+    ...envApi(t),
+    ...domainsApi(t),
+    ...networkApi(t),
+    ...traefikApi(t),
+    ...databasesApi(t),
+    ...volumesApi(t),
+    ...sourcesApi(t),
+    ...serversApi(t),
+    ...templatesApi(t),
+    ...settingsApi(t),
+    ...systemApi(t),
+    ...pluginsApi(t),
+    ...logsApi(t),
+    ...terminalsApi(t),
+  };
+}

package/src/databaseImport.ts

@@ -0,0 +1,174 @@
+// Database dump imports (0.14): resumable chunked uploads.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  DatabaseImport,
+  DatabaseImportCreate,
+  DatabaseImportOptions,
+} from '@ninedeploy/schemas';
+import { NineDeployError } from './errors.js';
+import type { Transport } from './transport.js';
+
+/** 0.14: an import that no longer changes (`DatabaseImport['status']`). */
+export const DATABASE_IMPORT_FINISHED_STATUSES: ReadonlyArray<DatabaseImport['status']> = [
+  'completed',
+  'completed_with_warnings',
+  'failed',
+  'cancelled',
+  'expired',
+];
+
+/** 0.14: `databases.imports.wait` polling options. */
+export interface ImportWaitOptions {
+  /**
+   * `finished` (default) waits for a final status; `uploaded` returns as soon
+   * as the import leaves `uploading` (an S3 download landing in `pending`).
+   */
+  until?: 'finished' | 'uploaded';
+  /** Poll interval, default 2000 ms. */
+  intervalMs?: number;
+  /** Give up after this long (default: never). Throws `import_wait_timeout`. */
+  timeoutMs?: number;
+  /** Called with every polled row. */
+  onStatus?: (row: DatabaseImport) => void;
+}
+
+/**
+ * 0.14: the bytes `databases.importFile` uploads. A factory receives the byte
+ * offset to resume from, so a seekable source (a browser `File`, a file
+ * handle) skips what the server already holds without re-reading it.
+ */
+export type ImportFileData = Uint8Array | AsyncIterable<Uint8Array> | ((offset: number) => AsyncIterable<Uint8Array>);
+
+/** 0.14: `databases.importFile` options. */
+export interface ImportFileOptions {
+  /** Required unless `data` is a Uint8Array (or `resumeImportId` is given). */
+  sizeBytes?: number;
+  filename?: string;
+  /** Hex sha256 of the whole file; the server checks it before starting. */
+  sha256?: string;
+  options?: DatabaseImportOptions;
+  /** Continue an `uploading` (or start a `pending`) import from where the server stands. */
+  resumeImportId?: number;
+  /** Start the import once uploaded (default true). */
+  start?: boolean;
+  /** Poll after starting until the import finishes. */
+  poll?: boolean | Omit<ImportWaitOptions, 'until'>;
+  /** Called once with the new import row (persist its id to resume later). */
+  onCreated?: (row: DatabaseImport) => void;
+  /** Called after every accepted chunk. */
+  onProgress?: (progress: { receivedBytes: number; sizeBytes: number; row: DatabaseImport }) => void;
+}
+
+/** 0.14: the import bytes from `offset` on (a factory seeks; the rest skip). */
+async function* sourceFrom(data: ImportFileData, offset: number): AsyncIterable<Uint8Array> {
+  if (data instanceof Uint8Array) {
+    yield data.subarray(offset);
+    return;
+  }
+  if (typeof data === 'function') {
+    yield* data(offset);
+    return;
+  }
+  let skip = offset;
+  for await (const piece of data) {
+    if (skip >= piece.length) {
+      skip -= piece.length;
+      continue;
+    }
+    yield skip > 0 ? piece.subarray(skip) : piece;
+    skip = 0;
+  }
+}
+
+/** 0.14: re-cut a byte stream into `size`-byte chunks (the last one shorter). */
+async function* rechunk(source: AsyncIterable<Uint8Array>, size: number): AsyncIterable<Uint8Array> {
+  let buf = new Uint8Array(size);
+  let len = 0;
+  for await (const piece of source) {
+    let at = 0;
+    while (at < piece.length) {
+      const take = Math.min(size - len, piece.length - at);
+      buf.set(piece.subarray(at, at + take), len);
+      len += take;
+      at += take;
+      if (len === size) {
+        yield buf;
+        buf = new Uint8Array(size);
+        len = 0;
+      }
+    }
+  }
+  if (len > 0) yield buf.subarray(0, len);
+}
+
+/** Chunked dump-import helpers bound to one transport (used by `databases`). */
+export function createImportHelpers(t: Transport) {
+  const { get, send, request } = t;
+  // ── 0.14 dump import helpers ─────────────────────────────────────────────
+  const importPath = (id: number, importId?: number) => `/v1/databases/${id}/imports${importId === undefined ? '' : `/${importId}`}`;
+  const getImport = (id: number, importId: number) => get<DatabaseImport>(importPath(id, importId));
+  /** An 8 MiB chunk over a slow uplink outlasts the default 30 s budget. */
+  const CHUNK_TIMEOUT_MS = 10 * 60_000;
+  const uploadChunk = (id: number, importId: number, index: number, chunk: Uint8Array) =>
+    request<DatabaseImport>(`${importPath(id, importId)}/chunks/${index}`, { method: 'PUT', raw: chunk }, CHUNK_TIMEOUT_MS);
+  const startImport = (id: number, importId: number) => send<DatabaseImport>('POST', `${importPath(id, importId)}/start`);
+  const sleep = (ms: number) =>
+    new Promise<void>((resolve) => {
+      (globalThis as unknown as { setTimeout: (fn: () => void, ms: number) => unknown }).setTimeout(resolve, ms);
+    });
+
+  async function waitForImport(id: number, importId: number, o: ImportWaitOptions = {}): Promise<DatabaseImport> {
+    const interval = o.intervalMs ?? 2000;
+    const deadline = o.timeoutMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + o.timeoutMs;
+    for (;;) {
+      const row = await getImport(id, importId);
+      o.onStatus?.(row);
+      const done = o.until === 'uploaded' ? row.status !== 'uploading' : DATABASE_IMPORT_FINISHED_STATUSES.includes(row.status);
+      if (done) return row;
+      if (Date.now() + interval > deadline) {
+        throw new NineDeployError(0, 'import_wait_timeout', `Import ${importId} is still ${row.status}`);
+      }
+      await sleep(interval);
+    }
+  }
+
+  async function importFile(id: number, data: ImportFileData, opts: ImportFileOptions = {}): Promise<DatabaseImport> {
+    const declared = data instanceof Uint8Array ? data.length : opts.sizeBytes;
+    let row: DatabaseImport;
+    if (opts.resumeImportId !== undefined) {
+      row = await getImport(id, opts.resumeImportId);
+    } else {
+      if (declared === undefined) throw new NineDeployError(0, 'import_size_required', 'sizeBytes is required for a streamed import');
+      const input: DatabaseImportCreate = { source: 'upload', sizeBytes: declared };
+      if (opts.sha256 !== undefined) input.sha256 = opts.sha256;
+      if (opts.filename !== undefined) input.filename = opts.filename;
+      if (opts.options !== undefined) input.options = opts.options;
+      row = await send<DatabaseImport>('POST', importPath(id), input);
+      opts.onCreated?.(row);
+    }
+    const size = row.sizeBytes;
+    const mismatch = (what: string) =>
+      new NineDeployError(0, 'import_size_mismatch', `The data is ${what} than the import's declared ${size} bytes`);
+    if (declared !== undefined && declared !== size) throw mismatch(declared > size ? 'larger' : 'smaller');
+
+    if (row.status === 'uploading') {
+      let index = row.receivedBytes / row.chunkSize;
+      for await (const chunk of rechunk(sourceFrom(data, row.receivedBytes), row.chunkSize)) {
+        if (row.receivedBytes + chunk.length > size) throw mismatch('larger');
+        row = await uploadChunk(id, row.id, index, chunk);
+        index += 1;
+        opts.onProgress?.({ receivedBytes: row.receivedBytes, sizeBytes: size, row });
+      }
+      if (row.receivedBytes < size) throw mismatch('smaller');
+    } else if (row.status !== 'pending') {
+      throw new NineDeployError(409, 'import_not_resumable', `Import ${row.id} is ${row.status}; only an uploading or pending import can continue`);
+    }
+    if (opts.start === false) return row;
+    row = await startImport(id, row.id);
+    if (!opts.poll) return row;
+    return waitForImport(id, row.id, opts.poll === true ? {} : opts.poll);
+  }
+
+  return { importPath, getImport, uploadChunk, startImport, waitForImport, importFile };
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+export interface ApiErrorBody {
+  error: { code: string; message: string; details?: unknown };
+}
+
+export class NineDeployError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly details?: unknown;
+
+  constructor(status: number, code: string, message: string, details?: unknown) {
+    super(message);
+    this.name = 'NineDeployError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+
+  static fromBody(status: number, body: unknown): NineDeployError {
+    const err = (body as ApiErrorBody | null)?.error;
+    return new NineDeployError(
+      status,
+      typeof err?.code === 'string' ? err.code : 'unknown_error',
+      typeof err?.message === 'string' ? err.message : `Request failed with status ${status}`,
+      err?.details,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+// @ninedeploy/sdk public entry. Every name below is part of the published API;
+// the implementation lives in the modules it re-exports from (resources/*.ts
+// hold one client surface each, client.ts composes them).
+export { NineDeployError } from './errors.js';
+export type * from '@ninedeploy/schemas';
+export {
+  detectProjectKind,
+  formatManifestYaml,
+  ManifestParseError,
+  ManifestValidationError,
+  parseManifestYaml,
+  starterManifest,
+  buildManifestFromTemplate,
+} from './manifest.js';
+export type { ProjectKind, TemplateRegistryEntry } from './manifest.js';
+
+export type {
+  FetchLike,
+  NineDeployClientOptions,
+} from './transport.js';
+
+export type {
+  JobKind,
+  ScheduledJob,
+  JobRun,
+  TraefikVersionInfo,
+  TraefikRoutingConfig,
+  HealthStatus,
+  VaultAllowlistView,
+  VaultSettings,
+  TokenIntrospection,
+  TemplateDeployResult,
+  TemplatePrepareResult,
+  ApplyManifestResult,
+  ApplyManifestInput,
+  BackupDrillResult,
+  BackupDrillEntry,
+  LogSearchInput,
+  LogSearchLine,
+  LogSearchResult,
+  EmailTemplateName,
+  EmailTemplateEntry,
+  EmailTemplateRender,
+  PgbouncerStatus,
+  ImageInfo,
+  PruneImagesInput,
+  PruneImagesResult,
+  DomainVerificationChallenge,
+  CreatedDomain,
+  DomainVerifyResult,
+  StartDomainTransferResult,
+  DomainTransferPreview,
+  AcceptDomainTransferInput,
+  AcceptDomainTransferResult,
+  DatabaseCredentialsWithPublic,
+  GithubAppInstallationSync,
+  SourceRepo,
+  SourceUpdateInput,
+  ServerListEntry,
+  ServerRolesResult,
+  SwarmJoinResult,
+  SwarmLeaveResult,
+  VolumeListEntry,
+  VolumeCreateResult,
+  ServiceDetail,
+  NodeTerminalCapability,
+  TerminalListQuery,
+  TrafficQuery,
+  ContainerInspectData,
+  ContainerComposeData,
+} from './types.js';
+
+export {
+  DATABASE_IMPORT_FINISHED_STATUSES,
+} from './databaseImport.js';
+
+export type {
+  ImportWaitOptions,
+  ImportFileData,
+  ImportFileOptions,
+} from './databaseImport.js';
+
+export type {
+  ApiQuery,
+} from './apiPath.js';
+
+export {
+  apiGetUrl,
+} from './apiPath.js';
+
+export {
+  AGENT_SWARM_MANAGER_VAR,
+} from './types.js';
+
+export {
+  TERMINAL_SUBPROTOCOL,
+  TERMINAL_TICKET_PREFIX,
+  TERMINAL_INPUT_CHUNK_BYTES,
+  TERMINAL_PENDING_INPUT_MAX,
+  terminalAttachInfo,
+  terminalCloseMessage,
+  connectTerminal,
+} from './terminal.js';
+
+export type {
+  TerminalAttachSource,
+  WebSocketLocation,
+  TerminalAttachInfo,
+  TerminalSocketLike,
+  TerminalSocketFactory,
+  TerminalReady,
+  TerminalHandlers,
+  TerminalConnectOptions,
+  TerminalConnection,
+} from './terminal.js';
+
+export { createClient } from './client.js';
+export type { NineDeployClient } from './client.js';