@fluxfiles/node 0.1.26 → 0.1.27

package/dist/index.d.mts

@@ -143,6 +143,12 @@ interface BaseTokenOptions {
     /** Edition preset that defaults a tier's claims (`pro`/`agency`/`enterprise`).
      *  DX sugar — explicit claim options still win, and the license gates the code. */
     edition?: 'free' | 'pro' | 'agency' | 'enterprise';
+    /** Role preset that defaults a person's capability level (perms, owner-scoping,
+     *  and free power-user toggles) — orthogonal to `edition`, which defaults which
+     *  *paid features* a tier gets. DX sugar — explicit claim options still win, and
+     *  `role` never itself becomes a JWT claim. See docs/ACL-ROLE-PRESETS-DESIGN.md.
+     *  Not supported on BYOB tokens (matches `edition`'s existing BYOB exclusion). */
+    role?: 'viewer' | 'editor' | 'admin' | 'superadmin';
     /** Paid-module claims (3-layer gate: code installed + licensed + this claim).
      *  All default off; inert unless the module is installed & licensed on the server. */
     allowShare?: boolean;
@@ -157,6 +163,10 @@ interface BaseTokenOptions {
     /** Allow the share landing to render an inline preview (images via /api/fm/img;
      *  PDFs only on uncapped shares). Default true; false = download-only. */
     sharePreview?: boolean;
+    /** Opt-in per-event analytics on a share link (visitor IP/user-agent persisted
+     *  to `_fluxfiles/share-events/<jti>.jsonl`) — kept separate from `allowShare`
+     *  since it's a real privacy footprint. Default false. */
+    shareAnalytics?: boolean;
     allowIntake?: boolean;
     /** Public base the intake create response builds the portal link from
      *  (e.g. `https://files.acme.com/public/intake.html`). http(s) only; empty = the

package/dist/index.d.ts

@@ -143,6 +143,12 @@ interface BaseTokenOptions {
     /** Edition preset that defaults a tier's claims (`pro`/`agency`/`enterprise`).
      *  DX sugar — explicit claim options still win, and the license gates the code. */
     edition?: 'free' | 'pro' | 'agency' | 'enterprise';
+    /** Role preset that defaults a person's capability level (perms, owner-scoping,
+     *  and free power-user toggles) — orthogonal to `edition`, which defaults which
+     *  *paid features* a tier gets. DX sugar — explicit claim options still win, and
+     *  `role` never itself becomes a JWT claim. See docs/ACL-ROLE-PRESETS-DESIGN.md.
+     *  Not supported on BYOB tokens (matches `edition`'s existing BYOB exclusion). */
+    role?: 'viewer' | 'editor' | 'admin' | 'superadmin';
     /** Paid-module claims (3-layer gate: code installed + licensed + this claim).
      *  All default off; inert unless the module is installed & licensed on the server. */
     allowShare?: boolean;
@@ -157,6 +163,10 @@ interface BaseTokenOptions {
     /** Allow the share landing to render an inline preview (images via /api/fm/img;
      *  PDFs only on uncapped shares). Default true; false = download-only. */
     sharePreview?: boolean;
+    /** Opt-in per-event analytics on a share link (visitor IP/user-agent persisted
+     *  to `_fluxfiles/share-events/<jti>.jsonl`) — kept separate from `allowShare`
+     *  since it's a real privacy footprint. Default false. */
+    shareAnalytics?: boolean;
     allowIntake?: boolean;
     /** Public base the intake create response builds the portal link from
      *  (e.g. `https://files.acme.com/public/intake.html`). http(s) only; empty = the

package/dist/index.js

@@ -84,12 +84,13 @@ function newJti() {
 function createToken(opts) {
   const secret = resolveSecret(opts.secret);
   const now = Math.floor(Date.now() / 1e3);
+  const rolePreset = opts.role ? ROLE_PRESETS[String(opts.role).toLowerCase()] : void 0;
   const payload = {
     sub: opts.userId,
     iat: now,
     exp: now + (opts.ttl ?? 3600),
     jti: newJti(),
-    perms: opts.perms ?? ["read"],
+    perms: opts.perms ?? (rolePreset == null ? void 0 : rolePreset.perms) ?? ["read"],
     disks: opts.disks ?? ["local"],
     prefix: opts.prefix ?? "",
     max_upload: opts.maxUploadMb ?? 10,
@@ -97,8 +98,8 @@ function createToken(opts) {
     max_storage: opts.maxStorageMb ?? 0,
     max_files: opts.maxFiles ?? 0
   };
-  if (opts.ownerOnly) payload.owner_only = true;
-  applyTenantOverrides(payload, opts);
+  if (opts.ownerOnly ?? (rolePreset == null ? void 0 : rolePreset.owner_only)) payload.owner_only = true;
+  applyTenantOverrides(payload, opts, rolePreset);
   return sign(payload, secret);
 }
 function createByobToken(opts) {
@@ -139,13 +140,61 @@ function sanitizeVariants(v) {
 var EDITION_PRESETS = {
   pro: { allow_optimize: true, allow_share: true, allow_intake: true },
   agency: { allow_optimize: true, allow_share: true, allow_intake: true },
-  enterprise: { allow_optimize: true, allow_share: true, allow_intake: true, allow_virus_scan: true, allow_c2pa: true }
+  studio: {
+    allow_optimize: true,
+    allow_share: true,
+    allow_intake: true,
+    allow_versioning: true,
+    allow_webhooks: true,
+    allow_ai_vision: true,
+    allow_ocr: true
+  },
+  enterprise: {
+    allow_optimize: true,
+    allow_share: true,
+    allow_intake: true,
+    allow_versioning: true,
+    allow_webhooks: true,
+    allow_ai_vision: true,
+    allow_ocr: true,
+    allow_virus_scan: true,
+    allow_c2pa: true,
+    allow_backup: true,
+    allow_audit_export: true,
+    allow_dlp_scan: true,
+    allow_legal_hold: true
+  }
 };
-function applyTenantOverrides(payload, opts) {
+var ROLE_PRESETS = {
+  viewer: { perms: ["read"], owner_only: true, allow_extract: false, allow_chmod: false },
+  editor: { perms: ["read", "write"], owner_only: true, allow_extract: true, allow_chmod: false },
+  admin: {
+    perms: ["read", "write", "delete", "audit"],
+    owner_only: false,
+    allow_extract: true,
+    allow_chmod: true,
+    allow_code_edit: true,
+    show_hidden: true
+  },
+  superadmin: {
+    perms: ["read", "write", "delete", "audit"],
+    owner_only: false,
+    allow_extract: true,
+    allow_chmod: true,
+    allow_code_edit: true,
+    show_hidden: true
+  }
+};
+function applyTenantOverrides(payload, opts, rolePreset) {
   const preset = opts.edition ? EDITION_PRESETS[String(opts.edition).toLowerCase()] : void 0;
   if (preset) {
     for (const [k, v] of Object.entries(preset)) if (!(k in payload)) payload[k] = v;
   }
+  if (rolePreset) {
+    for (const [k, v] of Object.entries(rolePreset)) {
+      if (k !== "perms" && k !== "owner_only" && !(k in payload)) payload[k] = v;
+    }
+  }
   if (opts.aiAutoTag !== void 0) payload.ai_auto_tag = !!opts.aiAutoTag;
   if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
   if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
@@ -181,6 +230,7 @@ function applyTenantOverrides(payload, opts) {
   if (opts.shareUrlTtl && opts.shareUrlTtl > 0) payload.share_url_ttl = Math.trunc(opts.shareUrlTtl);
   if (opts.shareBaseUrl) payload.share_base_url = String(opts.shareBaseUrl);
   if (opts.sharePreview !== void 0) payload.share_preview = !!opts.sharePreview;
+  if (opts.shareAnalytics !== void 0) payload.share_analytics = !!opts.shareAnalytics;
   if (opts.allowIntake !== void 0) payload.allow_intake = !!opts.allowIntake;
   if (opts.intakeBaseUrl) payload.intake_base_url = String(opts.intakeBaseUrl);
   if (opts.allowVersioning !== void 0) payload.allow_versioning = !!opts.allowVersioning;

package/dist/index.mjs

@@ -62,12 +62,13 @@ function newJti() {
 function createToken(opts) {
   const secret = resolveSecret(opts.secret);
   const now = Math.floor(Date.now() / 1e3);
+  const rolePreset = opts.role ? ROLE_PRESETS[String(opts.role).toLowerCase()] : void 0;
   const payload = {
     sub: opts.userId,
     iat: now,
     exp: now + (opts.ttl ?? 3600),
     jti: newJti(),
-    perms: opts.perms ?? ["read"],
+    perms: opts.perms ?? (rolePreset == null ? void 0 : rolePreset.perms) ?? ["read"],
     disks: opts.disks ?? ["local"],
     prefix: opts.prefix ?? "",
     max_upload: opts.maxUploadMb ?? 10,
@@ -75,8 +76,8 @@ function createToken(opts) {
     max_storage: opts.maxStorageMb ?? 0,
     max_files: opts.maxFiles ?? 0
   };
-  if (opts.ownerOnly) payload.owner_only = true;
-  applyTenantOverrides(payload, opts);
+  if (opts.ownerOnly ?? (rolePreset == null ? void 0 : rolePreset.owner_only)) payload.owner_only = true;
+  applyTenantOverrides(payload, opts, rolePreset);
   return sign(payload, secret);
 }
 function createByobToken(opts) {
@@ -117,13 +118,61 @@ function sanitizeVariants(v) {
 var EDITION_PRESETS = {
   pro: { allow_optimize: true, allow_share: true, allow_intake: true },
   agency: { allow_optimize: true, allow_share: true, allow_intake: true },
-  enterprise: { allow_optimize: true, allow_share: true, allow_intake: true, allow_virus_scan: true, allow_c2pa: true }
+  studio: {
+    allow_optimize: true,
+    allow_share: true,
+    allow_intake: true,
+    allow_versioning: true,
+    allow_webhooks: true,
+    allow_ai_vision: true,
+    allow_ocr: true
+  },
+  enterprise: {
+    allow_optimize: true,
+    allow_share: true,
+    allow_intake: true,
+    allow_versioning: true,
+    allow_webhooks: true,
+    allow_ai_vision: true,
+    allow_ocr: true,
+    allow_virus_scan: true,
+    allow_c2pa: true,
+    allow_backup: true,
+    allow_audit_export: true,
+    allow_dlp_scan: true,
+    allow_legal_hold: true
+  }
 };
-function applyTenantOverrides(payload, opts) {
+var ROLE_PRESETS = {
+  viewer: { perms: ["read"], owner_only: true, allow_extract: false, allow_chmod: false },
+  editor: { perms: ["read", "write"], owner_only: true, allow_extract: true, allow_chmod: false },
+  admin: {
+    perms: ["read", "write", "delete", "audit"],
+    owner_only: false,
+    allow_extract: true,
+    allow_chmod: true,
+    allow_code_edit: true,
+    show_hidden: true
+  },
+  superadmin: {
+    perms: ["read", "write", "delete", "audit"],
+    owner_only: false,
+    allow_extract: true,
+    allow_chmod: true,
+    allow_code_edit: true,
+    show_hidden: true
+  }
+};
+function applyTenantOverrides(payload, opts, rolePreset) {
   const preset = opts.edition ? EDITION_PRESETS[String(opts.edition).toLowerCase()] : void 0;
   if (preset) {
     for (const [k, v] of Object.entries(preset)) if (!(k in payload)) payload[k] = v;
   }
+  if (rolePreset) {
+    for (const [k, v] of Object.entries(rolePreset)) {
+      if (k !== "perms" && k !== "owner_only" && !(k in payload)) payload[k] = v;
+    }
+  }
   if (opts.aiAutoTag !== void 0) payload.ai_auto_tag = !!opts.aiAutoTag;
   if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
   if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
@@ -159,6 +208,7 @@ function applyTenantOverrides(payload, opts) {
   if (opts.shareUrlTtl && opts.shareUrlTtl > 0) payload.share_url_ttl = Math.trunc(opts.shareUrlTtl);
   if (opts.shareBaseUrl) payload.share_base_url = String(opts.shareBaseUrl);
   if (opts.sharePreview !== void 0) payload.share_preview = !!opts.sharePreview;
+  if (opts.shareAnalytics !== void 0) payload.share_analytics = !!opts.shareAnalytics;
   if (opts.allowIntake !== void 0) payload.allow_intake = !!opts.allowIntake;
   if (opts.intakeBaseUrl) payload.intake_base_url = String(opts.intakeBaseUrl);
   if (opts.allowVersioning !== void 0) payload.allow_versioning = !!opts.allowVersioning;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxfiles/node",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "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

@@ -34,12 +34,16 @@ function newJti(): string {
 export function createToken(opts: CreateTokenOptions): string {
   const secret = resolveSecret(opts.secret);
   const now = Math.floor(Date.now() / 1000);
+  // Role preset (DX sugar, docs/ACL-ROLE-PRESETS-DESIGN.md): resolved BEFORE the base
+  // payload object, because `perms` already has an unconditional default baked into
+  // that object below — a plain "set if absent" guard would never fire for it.
+  const rolePreset = opts.role ? ROLE_PRESETS[String(opts.role).toLowerCase()] : undefined;
   const payload: Record<string, unknown> = {
     sub: opts.userId,
     iat: now,
     exp: now + (opts.ttl ?? 3600),
     jti: newJti(),
-    perms: opts.perms ?? ['read'],
+    perms: opts.perms ?? (rolePreset?.perms as string[] | undefined) ?? ['read'],
     disks: opts.disks ?? ['local'],
     prefix: opts.prefix ?? '',
     max_upload: opts.maxUploadMb ?? 10,
@@ -47,8 +51,8 @@ export function createToken(opts: CreateTokenOptions): string {
     max_storage: opts.maxStorageMb ?? 0,
     max_files: opts.maxFiles ?? 0,
   };
-  if (opts.ownerOnly) payload.owner_only = true;
-  applyTenantOverrides(payload, opts);
+  if (opts.ownerOnly ?? (rolePreset?.owner_only as boolean | undefined)) payload.owner_only = true;
+  applyTenantOverrides(payload, opts, rolePreset);
   return sign(payload, secret);
 }
 
@@ -101,13 +105,49 @@ function sanitizeVariants(v: BaseTokenOptions['variants']): Record<string, numbe
 const EDITION_PRESETS: Record<string, Record<string, boolean>> = {
   pro: { allow_optimize: true, allow_share: true, allow_intake: true },
   agency: { allow_optimize: true, allow_share: true, allow_intake: true },
-  enterprise: { allow_optimize: true, allow_share: true, allow_intake: true, allow_virus_scan: true, allow_c2pa: true },
+  studio: {
+    allow_optimize: true, allow_share: true, allow_intake: true,
+    allow_versioning: true, allow_webhooks: true, allow_ai_vision: true, allow_ocr: true,
+  },
+  enterprise: {
+    allow_optimize: true, allow_share: true, allow_intake: true,
+    allow_versioning: true, allow_webhooks: true, allow_ai_vision: true, allow_ocr: true,
+    allow_virus_scan: true, allow_c2pa: true, allow_backup: true, allow_audit_export: true,
+    allow_dlp_scan: true, allow_legal_hold: true,
+  },
+};
+
+/** Role preset (DX sugar, docs/ACL-ROLE-PRESETS-DESIGN.md): default a person's
+ * capability level; explicit opts always win. `role` never itself becomes a JWT
+ * claim — it only ever expands into ordinary claims decoded server-side already. */
+const ROLE_PRESETS: Record<string, Record<string, unknown>> = {
+  viewer: { perms: ['read'], owner_only: true, allow_extract: false, allow_chmod: false },
+  editor: { perms: ['read', 'write'], owner_only: true, allow_extract: true, allow_chmod: false },
+  admin: {
+    perms: ['read', 'write', 'delete', 'audit'], owner_only: false,
+    allow_extract: true, allow_chmod: true, allow_code_edit: true, show_hidden: true,
+  },
+  superadmin: {
+    perms: ['read', 'write', 'delete', 'audit'], owner_only: false,
+    allow_extract: true, allow_chmod: true, allow_code_edit: true, show_hidden: true,
+  },
 };
 
 /** Copy the optional per-tenant override claims into a payload when set. */
-function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenOptions): void {
+function applyTenantOverrides(
+  payload: Record<string, unknown>,
+  opts: BaseTokenOptions,
+  rolePreset?: Record<string, unknown>,
+): void {
   const preset = opts.edition ? EDITION_PRESETS[String(opts.edition).toLowerCase()] : undefined;
   if (preset) for (const [k, v] of Object.entries(preset)) if (!(k in payload)) payload[k] = v;
+  // Role preset: the rest of the bundle, excluding `perms`/`owner_only` — both are
+  // already resolved above (in createToken()), before this function ever runs.
+  if (rolePreset) {
+    for (const [k, v] of Object.entries(rolePreset)) {
+      if (k !== 'perms' && k !== 'owner_only' && !(k in payload)) payload[k] = v;
+    }
+  }
   if (opts.aiAutoTag !== undefined) payload.ai_auto_tag = !!opts.aiAutoTag;
   if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
   if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
@@ -156,6 +196,7 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
   if (opts.shareUrlTtl && opts.shareUrlTtl > 0) payload.share_url_ttl = Math.trunc(opts.shareUrlTtl);
   if (opts.shareBaseUrl) payload.share_base_url = String(opts.shareBaseUrl);
   if (opts.sharePreview !== undefined) payload.share_preview = !!opts.sharePreview;
+  if (opts.shareAnalytics !== undefined) payload.share_analytics = !!opts.shareAnalytics;
   if (opts.allowIntake !== undefined) payload.allow_intake = !!opts.allowIntake;
   // Intake portal link base — same shape as shareBaseUrl (the core drops a
   // non-http(s) value on decode).

package/src/types.ts

@@ -147,6 +147,12 @@ export interface BaseTokenOptions {
   /** Edition preset that defaults a tier's claims (`pro`/`agency`/`enterprise`).
    *  DX sugar — explicit claim options still win, and the license gates the code. */
   edition?: 'free' | 'pro' | 'agency' | 'enterprise';
+  /** Role preset that defaults a person's capability level (perms, owner-scoping,
+   *  and free power-user toggles) — orthogonal to `edition`, which defaults which
+   *  *paid features* a tier gets. DX sugar — explicit claim options still win, and
+   *  `role` never itself becomes a JWT claim. See docs/ACL-ROLE-PRESETS-DESIGN.md.
+   *  Not supported on BYOB tokens (matches `edition`'s existing BYOB exclusion). */
+  role?: 'viewer' | 'editor' | 'admin' | 'superadmin';
   /** Paid-module claims (3-layer gate: code installed + licensed + this claim).
    *  All default off; inert unless the module is installed & licensed on the server. */
   allowShare?: boolean;
@@ -161,6 +167,10 @@ export interface BaseTokenOptions {
   /** Allow the share landing to render an inline preview (images via /api/fm/img;
    *  PDFs only on uncapped shares). Default true; false = download-only. */
   sharePreview?: boolean;
+  /** Opt-in per-event analytics on a share link (visitor IP/user-agent persisted
+   *  to `_fluxfiles/share-events/<jti>.jsonl`) — kept separate from `allowShare`
+   *  since it's a real privacy footprint. Default false. */
+  shareAnalytics?: boolean;
   allowIntake?: boolean;
   /** Public base the intake create response builds the portal link from
    *  (e.g. `https://files.acme.com/public/intake.html`). http(s) only; empty = the