@fluxfiles/node 0.1.6 → 0.1.8

package/dist/index.d.mts

@@ -5,7 +5,7 @@ type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
  * decrypted only at runtime by the FluxFiles server. Only S3-compatible
  * storage is allowed — the server rejects the `local` driver.
  */
-interface ByobDiskConfig {
+interface ByobS3DiskConfig {
     driver: 's3';
     key: string;
     secret: string;
@@ -17,6 +17,22 @@ interface ByobDiskConfig {
     /** Public base URL for direct (unsigned) object links on a public disk. */
     public_url?: string;
 }
+/**
+ * A BYOB SFTP disk — a user's own SFTP server (e.g. a VPS). Auth is a password OR
+ * a private key. The server SSRF-checks the host (no loopback/private/metadata
+ * targets). SFTP files are streamed through the app (no static/presigned URL).
+ */
+interface ByobSftpDiskConfig {
+    driver: 'sftp';
+    host: string;
+    username: string;
+    password?: string;
+    private_key?: string;
+    private_key_passphrase?: string;
+    port?: number;
+    root?: string;
+}
+type ByobDiskConfig = ByobS3DiskConfig | ByobSftpDiskConfig;
 /** Options shared by all token builders. */
 interface BaseTokenOptions {
     /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
@@ -83,6 +99,16 @@ interface BaseTokenOptions {
     watermarkOpacity?: number;
     /** Font size for text watermark. Default 24. */
     watermarkFontSize?: number;
+    /** Usage-summary cache TTL (seconds). `0`/omitted = inherit (900). */
+    usageCacheTtl?: number;
+    /** Percent at which quota status becomes "warning". `0`/omitted = inherit (70). */
+    usageWarningThreshold?: number;
+    /** Percent at which quota status becomes "critical". `0`/omitted = inherit (90). */
+    usageCriticalThreshold?: number;
+    /** Number of largest folders the usage dashboard returns. `0`/omitted = inherit (10). */
+    usageTopFoldersCount?: number;
+    /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
+    usageFolderDepth?: number;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.d.ts

@@ -5,7 +5,7 @@ type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
  * decrypted only at runtime by the FluxFiles server. Only S3-compatible
  * storage is allowed — the server rejects the `local` driver.
  */
-interface ByobDiskConfig {
+interface ByobS3DiskConfig {
     driver: 's3';
     key: string;
     secret: string;
@@ -17,6 +17,22 @@ interface ByobDiskConfig {
     /** Public base URL for direct (unsigned) object links on a public disk. */
     public_url?: string;
 }
+/**
+ * A BYOB SFTP disk — a user's own SFTP server (e.g. a VPS). Auth is a password OR
+ * a private key. The server SSRF-checks the host (no loopback/private/metadata
+ * targets). SFTP files are streamed through the app (no static/presigned URL).
+ */
+interface ByobSftpDiskConfig {
+    driver: 'sftp';
+    host: string;
+    username: string;
+    password?: string;
+    private_key?: string;
+    private_key_passphrase?: string;
+    port?: number;
+    root?: string;
+}
+type ByobDiskConfig = ByobS3DiskConfig | ByobSftpDiskConfig;
 /** Options shared by all token builders. */
 interface BaseTokenOptions {
     /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
@@ -83,6 +99,16 @@ interface BaseTokenOptions {
     watermarkOpacity?: number;
     /** Font size for text watermark. Default 24. */
     watermarkFontSize?: number;
+    /** Usage-summary cache TTL (seconds). `0`/omitted = inherit (900). */
+    usageCacheTtl?: number;
+    /** Percent at which quota status becomes "warning". `0`/omitted = inherit (70). */
+    usageWarningThreshold?: number;
+    /** Percent at which quota status becomes "critical". `0`/omitted = inherit (90). */
+    usageCriticalThreshold?: number;
+    /** Number of largest folders the usage dashboard returns. `0`/omitted = inherit (10). */
+    usageTopFoldersCount?: number;
+    /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
+    usageFolderDepth?: number;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.js

@@ -167,10 +167,26 @@ function applyTenantOverrides(payload, opts) {
     if (opts.watermarkOpacity !== void 0) payload.watermark_opacity = opts.watermarkOpacity;
     if (opts.watermarkFontSize && opts.watermarkFontSize > 0) payload.watermark_font_size = Math.trunc(opts.watermarkFontSize);
   }
+  if (opts.usageCacheTtl && opts.usageCacheTtl > 0) payload.usage_cache_ttl = Math.trunc(opts.usageCacheTtl);
+  if (opts.usageWarningThreshold && opts.usageWarningThreshold > 0) payload.usage_warning_threshold = Math.trunc(opts.usageWarningThreshold);
+  if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
+  if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
+  if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
 }
 function validateByobDisk(name, config) {
-  if (!config || config.driver !== "s3") {
-    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  if (!config || config.driver !== "s3" && config.driver !== "sftp") {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" or "sftp" (the server rejects "local").`);
+  }
+  if (config.driver === "sftp") {
+    for (const field of ["host", "username"]) {
+      if (!config[field]) {
+        throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+      }
+    }
+    if (!config.password && !config.private_key) {
+      throw new Error(`FluxFiles BYOB disk "${name}": needs a "password" or "private_key".`);
+    }
+    return;
   }
   for (const field of ["key", "secret", "bucket"]) {
     if (!config[field]) {

package/dist/index.mjs

@@ -145,10 +145,26 @@ function applyTenantOverrides(payload, opts) {
     if (opts.watermarkOpacity !== void 0) payload.watermark_opacity = opts.watermarkOpacity;
     if (opts.watermarkFontSize && opts.watermarkFontSize > 0) payload.watermark_font_size = Math.trunc(opts.watermarkFontSize);
   }
+  if (opts.usageCacheTtl && opts.usageCacheTtl > 0) payload.usage_cache_ttl = Math.trunc(opts.usageCacheTtl);
+  if (opts.usageWarningThreshold && opts.usageWarningThreshold > 0) payload.usage_warning_threshold = Math.trunc(opts.usageWarningThreshold);
+  if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
+  if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
+  if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
 }
 function validateByobDisk(name, config) {
-  if (!config || config.driver !== "s3") {
-    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  if (!config || config.driver !== "s3" && config.driver !== "sftp") {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" or "sftp" (the server rejects "local").`);
+  }
+  if (config.driver === "sftp") {
+    for (const field of ["host", "username"]) {
+      if (!config[field]) {
+        throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+      }
+    }
+    if (!config.password && !config.private_key) {
+      throw new Error(`FluxFiles BYOB disk "${name}": needs a "password" or "private_key".`);
+    }
+    return;
   }
   for (const field of ["key", "secret", "bucket"]) {
     if (!config[field]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxfiles/node",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Server-side Node/TypeScript SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core",
   "license": "MIT",
   "sideEffects": false,

package/src/token.ts

@@ -137,6 +137,13 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
     if (opts.watermarkOpacity !== undefined) payload.watermark_opacity = opts.watermarkOpacity;
     if (opts.watermarkFontSize && opts.watermarkFontSize > 0) payload.watermark_font_size = Math.trunc(opts.watermarkFontSize);
   }
+
+  // Usage-dashboard claims.
+  if (opts.usageCacheTtl && opts.usageCacheTtl > 0) payload.usage_cache_ttl = Math.trunc(opts.usageCacheTtl);
+  if (opts.usageWarningThreshold && opts.usageWarningThreshold > 0) payload.usage_warning_threshold = Math.trunc(opts.usageWarningThreshold);
+  if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
+  if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
+  if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
 }
 
 /**
@@ -144,8 +151,19 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
  * SSRF checks on the endpoint), so this only catches obvious mistakes early.
  */
 function validateByobDisk(name: string, config: ByobDiskConfig): void {
-  if (!config || config.driver !== 's3') {
-    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  if (!config || (config.driver !== 's3' && config.driver !== 'sftp')) {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" or "sftp" (the server rejects "local").`);
+  }
+  if (config.driver === 'sftp') {
+    for (const field of ['host', 'username'] as const) {
+      if (!config[field]) {
+        throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+      }
+    }
+    if (!config.password && !config.private_key) {
+      throw new Error(`FluxFiles BYOB disk "${name}": needs a "password" or "private_key".`);
+    }
+    return;
   }
   for (const field of ['key', 'secret', 'bucket'] as const) {
     if (!config[field]) {

package/src/types.ts

@@ -6,7 +6,7 @@ export type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
  * decrypted only at runtime by the FluxFiles server. Only S3-compatible
  * storage is allowed — the server rejects the `local` driver.
  */
-export interface ByobDiskConfig {
+export interface ByobS3DiskConfig {
   driver: 's3';
   key: string;
   secret: string;
@@ -19,6 +19,24 @@ export interface ByobDiskConfig {
   public_url?: string;
 }
 
+/**
+ * A BYOB SFTP disk — a user's own SFTP server (e.g. a VPS). Auth is a password OR
+ * a private key. The server SSRF-checks the host (no loopback/private/metadata
+ * targets). SFTP files are streamed through the app (no static/presigned URL).
+ */
+export interface ByobSftpDiskConfig {
+  driver: 'sftp';
+  host: string;
+  username: string;
+  password?: string;
+  private_key?: string;
+  private_key_passphrase?: string;
+  port?: number;
+  root?: string;
+}
+
+export type ByobDiskConfig = ByobS3DiskConfig | ByobSftpDiskConfig;
+
 /** Options shared by all token builders. */
 export interface BaseTokenOptions {
   /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
@@ -85,6 +103,16 @@ export interface BaseTokenOptions {
   watermarkOpacity?: number;
   /** Font size for text watermark. Default 24. */
   watermarkFontSize?: number;
+  /** Usage-summary cache TTL (seconds). `0`/omitted = inherit (900). */
+  usageCacheTtl?: number;
+  /** Percent at which quota status becomes "warning". `0`/omitted = inherit (70). */
+  usageWarningThreshold?: number;
+  /** Percent at which quota status becomes "critical". `0`/omitted = inherit (90). */
+  usageCriticalThreshold?: number;
+  /** Number of largest folders the usage dashboard returns. `0`/omitted = inherit (10). */
+  usageTopFoldersCount?: number;
+  /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
+  usageFolderDepth?: number;
 }
 
 export interface CreateTokenOptions extends BaseTokenOptions {