@ninedeploy/sdk 0.18.25 → 0.18.27

package/src/databaseImport.ts

@@ -5,6 +5,8 @@ import type {
   DatabaseImport,
   DatabaseImportCreate,
   DatabaseImportOptions,
+  VolumeImport,
+  VolumeImportCreate,
 } from '@ninedeploy/schemas';
 import { NineDeployError } from './errors.js';
 import type { Transport } from './transport.js';
@@ -18,8 +20,11 @@ export const DATABASE_IMPORT_FINISHED_STATUSES: ReadonlyArray<DatabaseImport['st
   'expired',
 ];
 
-/** 0.14: `databases.imports.wait` polling options. */
-export interface ImportWaitOptions {
+/** A1: a volume import that no longer changes (`VolumeImport['status']`). */
+export const VOLUME_IMPORT_FINISHED_STATUSES: ReadonlyArray<VolumeImport['status']> = ['completed', 'failed', 'cancelled', 'expired'];
+
+/** 0.14: `databases.imports.wait` (and A1 `volumeImports.wait`) polling options. */
+export interface ImportWaitOptions<Row = DatabaseImport> {
   /**
    * `finished` (default) waits for a final status; `uploaded` returns as soon
    * as the import leaves `uploading` (an S3 download landing in `pending`).
@@ -30,7 +35,7 @@ export interface ImportWaitOptions {
   /** Give up after this long (default: never). Throws `import_wait_timeout`. */
   timeoutMs?: number;
   /** Called with every polled row. */
-  onStatus?: (row: DatabaseImport) => void;
+  onStatus?: (row: Row) => void;
 }
 
 /**
@@ -60,6 +65,22 @@ export interface ImportFileOptions {
   onProgress?: (progress: { receivedBytes: number; sizeBytes: number; row: DatabaseImport }) => void;
 }
 
+/**
+ * A1: `volumeImports.importFile` options: a gzipped tar of a volume's
+ * contents, restored into a service's data volume. The sha256 is required
+ * (the server checks it before the volume is touched) unless resuming.
+ */
+export interface VolumeImportFileOptions {
+  sizeBytes?: number;
+  filename?: string;
+  sha256?: string;
+  resumeImportId?: number;
+  start?: boolean;
+  poll?: boolean | Omit<ImportWaitOptions<VolumeImport>, 'until'>;
+  onCreated?: (row: VolumeImport) => void;
+  onProgress?: (progress: { receivedBytes: number; sizeBytes: number; row: VolumeImport }) => 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) {
@@ -102,29 +123,51 @@ async function* rechunk(source: AsyncIterable<Uint8Array>, size: number): AsyncI
   if (len > 0) yield buf.subarray(0, len);
 }
 
-/** Chunked dump-import helpers bound to one transport (used by `databases`). */
-export function createImportHelpers(t: Transport) {
+interface UploadRow {
+  id: number;
+  status: string;
+  sizeBytes: number;
+  receivedBytes: number;
+  chunkSize: number;
+}
+interface UploadFileOptions<Row> {
+  sizeBytes?: number;
+  resumeImportId?: number;
+  start?: boolean;
+  poll?: boolean | Omit<ImportWaitOptions<Row>, 'until'>;
+  onCreated?: (row: Row) => void;
+  onProgress?: (progress: { receivedBytes: number; sizeBytes: number; row: Row }) => void;
+}
+
+/**
+ * The chunked, resumable upload shared by dump imports and volume imports:
+ * create (or resume) a row under `base(id)`, send ordered chunks of the
+ * size the server advertised, start, and optionally poll to a final status.
+ */
+function chunkedUploads<Row extends UploadRow, Opts extends UploadFileOptions<Row>>(
+  t: Transport,
+  cfg: { base: (id: number) => string; createBody: (sizeBytes: number, opts: Opts) => unknown; finished: ReadonlyArray<string> },
+) {
   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));
+  const importPath = (id: number, importId?: number) => `${cfg.base(id)}${importId === undefined ? '' : `/${importId}`}`;
+  const getImport = (id: number, importId: number) => get<Row>(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`);
+    request<Row>(`${importPath(id, importId)}/chunks/${index}`, { method: 'PUT', raw: chunk }, CHUNK_TIMEOUT_MS);
+  const startImport = (id: number, importId: number) => send<Row>('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> {
+  async function waitForImport(id: number, importId: number, o: ImportWaitOptions<Row> = {}): Promise<Row> {
     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);
+      const done = o.until === 'uploaded' ? row.status !== 'uploading' : cfg.finished.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}`);
@@ -133,18 +176,14 @@ export function createImportHelpers(t: Transport) {
     }
   }
 
-  async function importFile(id: number, data: ImportFileData, opts: ImportFileOptions = {}): Promise<DatabaseImport> {
+  async function importFile(id: number, data: ImportFileData, opts: Opts = {} as Opts): Promise<Row> {
     const declared = data instanceof Uint8Array ? data.length : opts.sizeBytes;
-    let row: DatabaseImport;
+    let row: Row;
     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);
+      row = await send<Row>('POST', importPath(id), cfg.createBody(declared, opts));
       opts.onCreated?.(row);
     }
     const size = row.sizeBytes;
@@ -172,3 +211,32 @@ export function createImportHelpers(t: Transport) {
 
   return { importPath, getImport, uploadChunk, startImport, waitForImport, importFile };
 }
+
+/** Chunked dump-import helpers bound to one transport (used by `databases`). */
+export function createImportHelpers(t: Transport) {
+  return chunkedUploads<DatabaseImport, ImportFileOptions>(t, {
+    base: (id) => `/v1/databases/${id}/imports`,
+    createBody: (sizeBytes, opts) => {
+      const input: DatabaseImportCreate = { source: 'upload', sizeBytes };
+      if (opts.sha256 !== undefined) input.sha256 = opts.sha256;
+      if (opts.filename !== undefined) input.filename = opts.filename;
+      if (opts.options !== undefined) input.options = opts.options;
+      return input;
+    },
+    finished: DATABASE_IMPORT_FINISHED_STATUSES,
+  });
+}
+
+/** A1: chunked volume-import helpers (`/v1/services/:id/volume-imports`). */
+export function createVolumeImportHelpers(t: Transport) {
+  return chunkedUploads<VolumeImport, VolumeImportFileOptions>(t, {
+    base: (id) => `/v1/services/${id}/volume-imports`,
+    createBody: (sizeBytes, opts) => {
+      if (opts.sha256 === undefined) throw new NineDeployError(0, 'import_sha256_required', "A volume import needs the archive's sha256");
+      const input: VolumeImportCreate = { sizeBytes, sha256: opts.sha256 };
+      if (opts.filename !== undefined) input.filename = opts.filename;
+      return input;
+    },
+    finished: VOLUME_IMPORT_FINISHED_STATUSES,
+  });
+}

package/src/index.ts

@@ -76,12 +76,14 @@ export type {
 
 export {
   DATABASE_IMPORT_FINISHED_STATUSES,
+  VOLUME_IMPORT_FINISHED_STATUSES,
 } from './databaseImport.js';
 
 export type {
   ImportWaitOptions,
   ImportFileData,
   ImportFileOptions,
+  VolumeImportFileOptions,
 } from './databaseImport.js';
 
 export type {

package/src/resources/auth.ts

@@ -14,6 +14,7 @@ import type {
   PublicUser,
   Refresh,
   Register,
+  Setup,
   Session,
   UserCreate,
   WorkspaceEntry,
@@ -48,7 +49,7 @@ import type { Transport } from '../transport.js';
 export interface AuthApi {
   auth: {
     /** `setupTokenRequired` (0.16): the first-run bootstrap needs the installer's setup token. */
-    status: () => Promise<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean }>;
+    status: () => Promise<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean; acmeConfigured?: boolean }>;
     /**
      * Introspect the current bearer token. Returns the
      * token's id (when opaque), name, scopes, expiry and
@@ -58,7 +59,7 @@ export interface AuthApi {
      * tools.
      */
     introspectToken: () => Promise<TokenIntrospection>;
-    setup: (input: Register) => Promise<Session>;
+    setup: (input: Setup) => Promise<Session>;
     register: (input: Register) => Promise<Session>;
     login: (input: Login) => Promise<Session>;
     refresh: (input: Refresh) => Promise<Session>;
@@ -249,7 +250,7 @@ export function authApi(t: Transport): AuthApi {
   const { get, send, request } = t;
   return {
     auth: {
-      status: () => get<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean }>('/v1/auth/status'),
+      status: () => get<{ initialized: boolean; allowRegistration?: boolean; setupTokenRequired?: boolean; acmeConfigured?: boolean }>('/v1/auth/status'),
       introspectToken: () => get<TokenIntrospection>('/v1/auth/token'),
       setup: (input) => send<Session>('POST', '/v1/setup', input),
       register: (input) => send<Session>('POST', '/v1/auth/register', input),

package/src/resources/databases.ts

@@ -15,6 +15,8 @@ import type {
   PublicAccessStatus,
   DatabaseImport,
   DatabaseImportCreate,
+  DatabaseUpgrade,
+  DatabaseUpgradeOptions,
   BackupDestinationObject,
   BackupReplica,
   BackupReplicasView,
@@ -104,6 +106,25 @@ export interface DatabasesApi {
       recoveries: (id: number) => Promise<PitrRecovery[]>;
       recovery: (id: number, recoveryId: number) => Promise<PitrRecovery>;
     };
+    /**
+     * O2: major-version upgrades (PostgreSQL on the panel host). `options`
+     * reads the running cluster's major and what it can move to. `start`
+     * checks the cluster, then answers 202 with the running upgrade: the
+     * database is stopped, dumped (the dump is kept in its backups), restored
+     * into a new volume on the target major and compared before the switch.
+     * The previous volume stays until `finalize`; until then `rollback`
+     * points the database back at it. Starting, rolling back and finalizing
+     * need `admin` on the database.
+     */
+    upgrades: {
+      list: (id: number) => Promise<DatabaseUpgrade[]>;
+      options: (id: number) => Promise<DatabaseUpgradeOptions>;
+      start: (id: number, input: { toMajor: number }) => Promise<DatabaseUpgrade>;
+      rollback: (id: number, upgradeId: number) => Promise<DatabaseUpgrade>;
+      finalize: (id: number, upgradeId: number) => Promise<DatabaseUpgrade & { removedVolume: string }>;
+      /** Poll until the upgrade is no longer `running` (default every 2 s, for up to 2 h). */
+      wait: (id: number, upgradeId: number, opts?: { intervalMs?: number; timeoutMs?: number }) => Promise<DatabaseUpgrade>;
+    };
     /**
      * 0.14: public access through a per-database Traefik TCP sidecar. Reading
      * needs `admin` on the database; `set` and `disable` are operator-only.
@@ -224,6 +245,24 @@ export function databasesApi(t: Transport): DatabasesApi {
         recoveries: (id) => get<PitrRecovery[]>(`/v1/databases/${id}/pitr/recoveries`),
         recovery: (id, recoveryId) => get<PitrRecovery>(`/v1/databases/${id}/pitr/recoveries/${recoveryId}`),
       },
+      upgrades: {
+        list: (id) => get<DatabaseUpgrade[]>(`/v1/databases/${id}/upgrades`),
+        options: (id) => get<DatabaseUpgradeOptions>(`/v1/databases/${id}/upgrades/options`),
+        start: (id, input) => send<DatabaseUpgrade>('POST', `/v1/databases/${id}/upgrades`, input),
+        rollback: (id, upgradeId) => send<DatabaseUpgrade>('POST', `/v1/databases/${id}/upgrades/${upgradeId}/rollback`, {}),
+        finalize: (id, upgradeId) => send<DatabaseUpgrade & { removedVolume: string }>('POST', `/v1/databases/${id}/upgrades/${upgradeId}/finalize`, {}),
+        wait: async (id, upgradeId, opts = {}) => {
+          const interval = opts.intervalMs ?? 2_000;
+          const deadline = Date.now() + (opts.timeoutMs ?? 2 * 60 * 60 * 1000);
+          for (;;) {
+            const row = (await get<DatabaseUpgrade[]>(`/v1/databases/${id}/upgrades`)).find((u) => u.id === upgradeId);
+            if (!row) throw new Error(`upgrade ${upgradeId} of database ${id} not found`);
+            if (row.status !== 'running') return row;
+            if (Date.now() >= deadline) throw new Error(`upgrade ${upgradeId} is still running (phase ${row.phase ?? 'unknown'})`);
+            await new Promise<void>((resolve) => (globalThis as unknown as { setTimeout: (fn: () => void, ms: number) => unknown }).setTimeout(resolve, interval));
+          }
+        },
+      },
       pgbouncerStatus: (id) => get<PgbouncerStatus>(`/v1/databases/${id}/pgbouncer`),
       enablePgbouncer: (id, input) =>
         send<PgbouncerStatus>('POST', `/v1/databases/${id}/pgbouncer/enable`, input ?? {}),

package/src/resources/services.ts

@@ -7,6 +7,7 @@ import type {
   SizingReport,
   RestartLimitConfig,
   RestartLimitView,
+  ServiceCapabilitiesView,
   PendingChangesView,
   PendingApplyInput,
   PendingApplyResult,
@@ -270,6 +271,8 @@ export interface ServicesApi {
       enable: (id: number) => Promise<RegistryHookView>;
       disable: (id: number) => Promise<RegistryHookView>;
     };
+    /** C1: what the service can use where it runs, and why not (viewer). */
+    capabilities: (id: number) => Promise<ServiceCapabilitiesView>;
     /** G1.3: stop the service when its containers keep restarting (opt-in; member to set). */
     restartLimit: {
       get: (id: number) => Promise<RestartLimitView>;
@@ -471,6 +474,7 @@ export function servicesApi(t: Transport): ServicesApi {
         enable: (id) => send<RegistryHookView>('POST', `/v1/services/${id}/registry-hook`),
         disable: (id) => request<RegistryHookView>(`/v1/services/${id}/registry-hook`, { method: 'DELETE' }),
       },
+      capabilities: (id) => get<ServiceCapabilitiesView>(`/v1/services/${id}/capabilities`),
       restartLimit: {
         get: (id) => get<RestartLimitView>(`/v1/services/${id}/restart-limit`),
         set: (id, limit) => send<RestartLimitView>('PUT', `/v1/services/${id}/restart-limit`, { limit }),

package/src/resources/settings.ts

@@ -17,6 +17,8 @@ import type {
   ExecProviderPut,
   McpHttpPolicyPatch,
   McpHttpPolicyView,
+  PanelAccessUpdate,
+  PanelAccessView,
 } from '@ninedeploy/schemas';
 import type { VaultAllowlistView, VaultSettings, EmailTemplateName, EmailTemplateEntry, EmailTemplateRender } from '../types.js';
 import type { Transport } from '../transport.js';
@@ -84,6 +86,14 @@ export interface SettingsApi {
     setAllowRegistration: (enabled: boolean) => Promise<{ ok: boolean; allowRegistration: boolean }>;
     setAcmeEmail: (email: string) => Promise<{ ok: boolean; acmeEmail: string | null; applied: string }>;
     setTemplatesSource: (source: string) => Promise<{ ok: boolean; templatesSource: string | null }>;
+    /**
+     * O4: the panel IP allow-list (operator, interactive session). `set`
+     * is refused when the list would exclude the caller's own address.
+     */
+    panelAccess: {
+      get: () => Promise<PanelAccessView>;
+      set: (input: PanelAccessUpdate) => Promise<PanelAccessView>;
+    };
     /** Configure the ACME DNS-01 challenge (wildcard certificates). */
     setDns: (input: { provider: string; token?: string; wildcardApex: string }) => Promise<{ ok: boolean; dnsProvider: string | null; wildcardApex: string | null; applied: string }>;
     /**
@@ -266,6 +276,10 @@ export function settingsApi(t: Transport): SettingsApi {
         send<{ ok: boolean; acmeEmail: string | null; applied: string }>('PUT', '/v1/settings/acme-email', { email }),
       setTemplatesSource: (source) =>
         send<{ ok: boolean; templatesSource: string | null }>('PUT', '/v1/settings/templates-source', { source }),
+      panelAccess: {
+        get: () => get<PanelAccessView>('/v1/settings/panel-access'),
+        set: (input) => send<PanelAccessView>('PUT', '/v1/settings/panel-access', input),
+      },
       setDns: (input) =>
         send<{ ok: boolean; dnsProvider: string | null; wildcardApex: string | null; applied: string }>('PUT', '/v1/settings/dns', input),
       autoUrl: {

package/src/resources/system.ts

@@ -17,6 +17,7 @@ import type {
   StatsSnapshot,
   TopologyGraph,
   UpdateCheckResult,
+  UpdateChannel,
   SelfUpdateStatus,
   AutoPruneConfigUpdateInput,
   AutoPruneStatus,
@@ -55,6 +56,11 @@ export interface SystemApi {
     exportUrl: () => string;
     /** Latest-release check (admin). updateAvailable is null when offline/disabled. */
     updateCheck: (force?: boolean) => Promise<UpdateCheckResult>;
+    /** A6: which releases the panel offers — every release, or the stable channel (operator). */
+    updateChannel: {
+      get: () => Promise<{ channel: UpdateChannel }>;
+      set: (channel: UpdateChannel) => Promise<{ channel: UpdateChannel; check: UpdateCheckResult }>;
+    };
     /** State of a panel-initiated upgrade (idle/running/success/failed/unsupported). */
     updateStatus: () => Promise<SelfUpdateStatus>;
     /**
@@ -214,6 +220,10 @@ export function systemApi(t: Transport): SystemApi {
       resources: () => get<DockerResources>('/v1/system/resources'),
       pruneImages: () => send<{ ok: boolean }>('POST', '/v1/system/prune-images'),
       updateCheck: (force) => get<UpdateCheckResult>(`/v1/system/update-check${force ? '?force=1' : ''}`),
+      updateChannel: {
+        get: () => get<{ channel: UpdateChannel }>('/v1/system/update-channel'),
+        set: (channel) => send<{ channel: UpdateChannel; check: UpdateCheckResult }>('PUT', '/v1/system/update-channel', { channel }),
+      },
       updateStatus: () => get<SelfUpdateStatus>('/v1/system/update-status'),
       updateStart: (version, opts) => send<{ ok: boolean }>('POST', '/v1/system/update-start', { version, ...opts }),
       exportUrl: () => '/v1/system/export',

package/src/resources/volumes.ts

@@ -9,7 +9,9 @@ import type {
   VolumeFileWriteInput,
   VolumePathCreateInput,
   VolumeCreateInput,
+  VolumeImport,
 } from '@ninedeploy/schemas';
+import { createVolumeImportHelpers, type ImportFileData, type ImportWaitOptions, type VolumeImportFileOptions } from '../databaseImport.js';
 import { apiGetUrl } from '../apiPath.js';
 import type { VolumeListEntry, VolumeCreateResult, ContainerInspectData, ContainerComposeData } from '../types.js';
 import type { Transport } from '../transport.js';
@@ -78,10 +80,28 @@ export interface VolumesApi {
       input: { filePath: string; attachmentId?: number; volumeName?: string },
     ) => Promise<{ ok: boolean; deploymentId: number }>;
   };
+  /**
+   * A1: restore a gzipped tar of another host's volume into a service's data
+   * volume (`nd-svc-<slug>-data`). Operator only; docker services on the
+   * panel host with a volume mount. Uploads in ordered chunks with the
+   * archive's sha256; `start` is refused while the service runs, and a volume
+   * that exists is snapshotted first (a `pre-import` volume backup). A panel
+   * older than this feature answers 404.
+   */
+  volumeImports: {
+    list: (serviceId: number) => Promise<VolumeImport[]>;
+    get: (serviceId: number, importId: number) => Promise<VolumeImport>;
+    cancel: (serviceId: number, importId: number) => Promise<VolumeImport>;
+    start: (serviceId: number, importId: number) => Promise<VolumeImport>;
+    wait: (serviceId: number, importId: number, options?: ImportWaitOptions<VolumeImport>) => Promise<VolumeImport>;
+    /** Create (or resume), upload, start and optionally poll, like `databases.importFile`. */
+    importFile: (serviceId: number, data: ImportFileData, options?: VolumeImportFileOptions) => Promise<VolumeImport>;
+  };
 }
 
 export function volumesApi(t: Transport): VolumesApi {
   const { get, send, request } = t;
+  const vi = createVolumeImportHelpers(t);
   const volumePath = (name: string, suffix: string, options?: { serverId?: number }) => {
     const id = options?.serverId;
     if (id != null && (!Number.isSafeInteger(id) || id < 1)) throw new TypeError('Invalid volume node id');
@@ -148,5 +168,13 @@ export function volumesApi(t: Transport): VolumesApi {
       repairConfig: (serviceId, input) =>
         send<{ ok: boolean; deploymentId: number }>('POST', `/v1/services/${serviceId}/volumes/config-repair`, input),
     },
+    volumeImports: {
+      list: (serviceId) => get<VolumeImport[]>(vi.importPath(serviceId)),
+      get: vi.getImport,
+      cancel: (serviceId, importId) => send<VolumeImport>('DELETE', vi.importPath(serviceId, importId)),
+      start: vi.startImport,
+      wait: vi.waitForImport,
+      importFile: vi.importFile,
+    },
   };
 }