@profullstack/coinpay 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.22.0] - 2026-10-19
+
+### Added
+- `coinpay document publish <dir> --business-id <id>`: encrypt and publish a whole directory, keeping
+  its structure (under a folder named like the directory, or `--folder dest`, `--folder /` for the top
+  level). Publishing again syncs: new files upload, changed files become a new version, unchanged files
+  are skipped, signed documents are left alone, nothing remote is deleted. `--dry-run` shows the plan;
+  hidden files and `node_modules` are skipped unless `--include-hidden`.
+- `coinpay document move <id> <folder>`; `upload --folder a/b`; `list` shows folders.
+- Any file type can be uploaded (unknown types are opaque downloads; the server only holds ciphertext).
+- SDK: `publishDirectory`, `planPublish`, `moveDocument`; `uploadDocument({ folder })`.
+
 ## [0.21.0] - 2026-10-19
 
 ### Added

package/bin/coinpay.js

@@ -80,7 +80,9 @@ import {
   downloadDocument,
   listDocumentVersions,
   uploadDocumentVersion,
+  moveDocument,
 } from '../src/documents.js';
+import { publishDirectory } from '../src/documents-publish.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -552,7 +554,11 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bright}document${colors.reset}  (end-to-end encrypted: CoinPay never sees the contents)
     vault-setup           Create the documents passphrase (--business-id, admins)
     list                  Documents (--business-id) with signing progress
-    upload <file>         Encrypt and upload: --business-id [--title] [--message]
+    upload <file>         Encrypt and upload: --business-id [--folder a/b] [--title] [--message]
+    publish <dir>         Sync a whole directory, keeping its structure: --business-id
+                          [--folder dest | --folder / for top level] [--dry-run] [--include-hidden]
+                          new files upload, changed ones become versions, signed ones are left alone
+    move <id> <folder>    File a document elsewhere (/ = top level)
     share <id>            --signers "Ada <ada@x.com>, bob@y.com" [--editors "..."] [--viewers "..."]
                           [--message] [--no-email] [--email-key puts the key in the email]
                           Prints each full link (with #k= key): send it privately
@@ -1328,7 +1334,7 @@ async function documentsVault(client, businessId) {
 
 async function handleDocument(subcommand, args, flags) {
   const client = createClient();
-  requireFlagValues(flags, ['business-id', 'title', 'message', 'signers', 'viewers', 'editors', 'reason', 'out', 'note', 'revision']);
+  requireFlagValues(flags, ['business-id', 'title', 'message', 'signers', 'viewers', 'editors', 'reason', 'out', 'note', 'revision', 'folder']);
   switch (subcommand) {
     case 'vault-setup': {
       if (!flags['business-id']) usageExit('coinpay document vault-setup --business-id <id>');
@@ -1344,12 +1350,56 @@ async function handleDocument(subcommand, args, flags) {
       if (!rows.length) return print.info('No documents');
       for (const d of rows) {
         const progress = d.signers ? '  ' + d.signed + '/' + d.signers + ' signed' : '';
-        print.info(d.id + '  ' + d.title + '  ' + d.status + progress);
+        print.info(d.id + '  ' + (d.folder ? d.folder + '/' : '') + d.title + '  ' + d.status + progress);
       }
       return;
     }
+    case 'publish': {
+      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document publish <dir> --business-id <id> [--folder path | --folder /] [--dry-run] [--include-hidden]');
+      if (!existsSync(args[0])) usageExit('No such directory: ' + args[0]);
+      const businessId = flags['business-id'];
+      const dryRun = !!flags['dry-run'];
+      const vault = dryRun ? undefined : await documentsVault(client, businessId);
+      const labels = { upload: 'new', version: 'new version', unchanged: 'unchanged', locked: 'signed, left alone', too_large: 'too large (9 MB max)', empty: 'empty, skipped' };
+      const result = await publishDirectory(client, {
+        businessId,
+        vault,
+        dir: args[0],
+        folder: flags.folder,
+        includeHidden: !!flags['include-hidden'],
+        dryRun,
+        onFile: (p) => {
+          if (flags.json) return;
+          const where = (p.folder ? p.folder + '/' : '') + p.filename;
+          if (p.result === 'ok') print.success((p.action === 'upload' ? 'uploaded ' : 'v' + p.version + ' ') + where);
+          else print.error('failed ' + where + ': ' + p.error);
+        },
+      });
+      if (flags.json) return print.json(result);
+      const count = (a) => result.plan.filter((p) => p.action === a).length;
+      if (dryRun) {
+        for (const p of result.plan) print.info(labels[p.action].padEnd(20) + ' ' + (p.folder ? p.folder + '/' : '') + p.filename);
+        print.info('Dry run: nothing was uploaded.');
+      }
+      const failed = result.plan.filter((p) => p.result === 'failed').length;
+      print.info(
+        'Into ' + (result.folder ? result.folder + '/' : 'the top level') + ': ' +
+          count('upload') + ' new, ' + count('version') + ' new versions, ' + count('unchanged') + ' unchanged' +
+          (count('locked') ? ', ' + count('locked') + ' signed (left alone)' : '') +
+          (count('too_large') ? ', ' + count('too_large') + ' too large' : '') +
+          (result.skippedHidden ? ', ' + result.skippedHidden + ' hidden skipped' : '') +
+          (failed ? ', ' + failed + ' FAILED' : '')
+      );
+      if (failed) process.exitCode = 1;
+      return;
+    }
+    case 'move': {
+      if (args.length !== 2) usageExit('coinpay document move <id> <folder>   (use / for the top level)');
+      const result = await moveDocument(client, args[0], args[1]);
+      return flags.json ? print.json(result) : print.success('Moved to ' + (result.folder || 'the top level'));
+    }
     case 'upload': {
-      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document upload <file> --business-id <id> [--title "..."] [--message "..."]');
+      if (args.length !== 1 || !flags['business-id']) usageExit('coinpay document upload <file> --business-id <id> [--folder path] [--title "..."] [--message "..."]');
       const vault = await documentsVault(client, flags['business-id']);
       const doc = await uploadDocument(client, {
         businessId: flags['business-id'],
@@ -1358,6 +1408,7 @@ async function handleDocument(subcommand, args, flags) {
         filename: args[0],
         title: flags.title,
         message: flags.message,
+        folder: flags.folder,
       });
       if (flags.json) return print.json(doc);
       print.success('Uploaded (encrypted): ' + doc.id);
@@ -1445,7 +1496,7 @@ async function handleDocument(subcommand, args, flags) {
       return print.success('Deleted');
     }
     default:
-      usageExit('coinpay document <vault-setup|list|upload|share|get|versions|new-version|link|revoke|download|void|delete>');
+      usageExit('coinpay document <vault-setup|list|upload|publish|move|share|get|versions|new-version|link|revoke|download|void|delete>');
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",

package/src/documents-publish.d.ts

@@ -0,0 +1,29 @@
+import type { CoinPayClient } from './client.js';
+import type { CoinPayDocument, UnlockedVault } from './documents.js';
+
+export interface PublishEntry {
+  abs: string;
+  rel: string;
+  size: number;
+  filename: string;
+  folder: string | null;
+  sha256?: string;
+  action: 'upload' | 'version' | 'unchanged' | 'locked' | 'too_large' | 'empty';
+  documentId?: string;
+  version?: number;
+  result?: 'ok' | 'failed';
+  error?: string;
+}
+
+export interface PublishResult {
+  plan: PublishEntry[];
+  skippedHidden: number;
+  folder: string | null;
+}
+
+export function walkDirectory(dir: string, opts?: { includeHidden?: boolean }): Promise<{ files: { abs: string; rel: string; size: number }[]; skipped: number }>;
+export function planPublish(local: Omit<PublishEntry, 'action'>[], remote: Pick<CoinPayDocument, 'id' | 'folder' | 'filename' | 'sha256' | 'status' | 'signed'>[]): PublishEntry[];
+export function publishDirectory(
+  client: CoinPayClient,
+  opts: { businessId: string; vault?: UnlockedVault; dir: string; folder?: string; includeHidden?: boolean; dryRun?: boolean; concurrency?: number; onFile?: (entry: PublishEntry) => void }
+): Promise<PublishResult>;

package/src/documents-publish.js

@@ -0,0 +1,110 @@
+/**
+ * Publish a local directory to a business's documents: every file is
+ * encrypted on this machine (see documents.js) and filed under the same
+ * folder structure. Publishing again syncs: new files are uploaded, changed
+ * files become a new version, unchanged ones are skipped, and documents that
+ * are already signed are never touched. Nothing remote is ever deleted.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import {
+  isSkippedPath,
+  listDocuments,
+  MAX_DOCUMENT_BYTES,
+  normalizeFolder,
+  sha256Hex,
+  uploadDocument,
+  uploadDocumentVersion,
+} from './documents.js';
+
+/** Every file under `dir`, with its path relative to `dir` ('/'-separated). Symlinks are not followed. */
+export async function walkDirectory(dir, { includeHidden = false } = {}) {
+  const root = resolve(dir);
+  const out = [];
+  let skipped = 0;
+  const visit = async (abs) => {
+    for (const entry of await readdir(abs, { withFileTypes: true })) {
+      const child = join(abs, entry.name);
+      const rel = relative(root, child).split(sep).join('/');
+      if (!includeHidden && isSkippedPath(rel)) {
+        skipped++;
+        continue;
+      }
+      if (entry.isDirectory()) await visit(child);
+      else if (entry.isFile()) out.push({ abs: child, rel, size: (await stat(child)).size });
+    }
+  };
+  await visit(root);
+  out.sort((a, b) => a.rel.localeCompare(b.rel));
+  return { files: out, skipped };
+}
+
+const key = (folder, filename) => `${folder ?? ''}\u0000${filename}`;
+
+/**
+ * Decide what to do with each local file. `remote` is listDocuments() output
+ * (newest first, so the first match for a path wins). Pure: no I/O.
+ *
+ * Actions: upload | version | unchanged | locked (signed, completed, declined
+ * or voided remotely) | too_large | empty.
+ */
+export function planPublish(local, remote) {
+  const byPath = new Map();
+  for (const d of remote) if (!byPath.has(key(d.folder, d.filename))) byPath.set(key(d.folder, d.filename), d);
+  return local.map((f) => {
+    if (f.size === 0) return { ...f, action: 'empty' };
+    if (f.size > MAX_DOCUMENT_BYTES) return { ...f, action: 'too_large' };
+    const existing = byPath.get(key(f.folder, f.filename));
+    if (!existing) return { ...f, action: 'upload' };
+    if (existing.sha256 === f.sha256) return { ...f, action: 'unchanged', documentId: existing.id };
+    const locked = ['completed', 'declined', 'voided'].includes(existing.status) || (existing.signed ?? 0) > 0;
+    return { ...f, action: locked ? 'locked' : 'version', documentId: existing.id, status: existing.status };
+  });
+}
+
+/**
+ * Publish `dir`. `folder` is where its contents go: by default a folder named
+ * like the directory (as a desktop copy would); pass '' or '/' for the top level.
+ */
+export async function publishDirectory(client, { businessId, vault, dir, folder, includeHidden = false, dryRun = false, concurrency = 3, onFile } = {}) {
+  if (!businessId) throw new Error('businessId is required');
+  const prefix = normalizeFolder(folder === undefined ? basename(resolve(dir)) : folder);
+  const { files, skipped } = await walkDirectory(dir, { includeHidden });
+
+  const local = [];
+  for (const f of files) {
+    const parts = f.rel.split('/');
+    const filename = parts.pop();
+    const entry = { ...f, filename, folder: normalizeFolder([prefix ?? '', ...parts].join('/')) };
+    if (f.size > 0 && f.size <= MAX_DOCUMENT_BYTES) entry.sha256 = await sha256Hex(await readFile(f.abs));
+    local.push(entry);
+  }
+  const plan = planPublish(local, await listDocuments(client, { businessId }));
+  if (dryRun) return { plan, skippedHidden: skipped, folder: prefix };
+
+  let next = 0;
+  const work = plan.filter((p) => p.action === 'upload' || p.action === 'version');
+  const worker = async () => {
+    while (next < work.length) {
+      const p = work[next++];
+      try {
+        const bytes = await readFile(p.abs);
+        if (p.action === 'upload') {
+          const doc = await uploadDocument(client, { businessId, vault, bytes, filename: p.filename, folder: p.folder });
+          p.documentId = doc.id;
+        } else {
+          const result = await uploadDocumentVersion(client, p.documentId, { vault, bytes, filename: p.filename, note: 'published from ' + p.rel });
+          p.version = result.version;
+        }
+        p.result = 'ok';
+      } catch (err) {
+        p.result = 'failed';
+        p.error = err.message;
+      }
+      onFile?.(p);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, work.length) }, worker));
+  return { plan, skippedHidden: skipped, folder: prefix };
+}

package/src/documents.d.ts

@@ -5,6 +5,7 @@ export interface CoinPayDocument {
   business_id: string;
   title: string;
   message: string | null;
+  folder: string | null;
   filename: string;
   content_type: string;
   bytes: number;
@@ -62,12 +63,15 @@ export interface UnlockedVault {
   version: number;
 }
 
-export function listDocuments(client: CoinPayClient, opts?: { businessId?: string; status?: string }): Promise<CoinPayDocument[]>;
+export function listDocuments(client: CoinPayClient, opts?: { businessId?: string; status?: string; folder?: string }): Promise<CoinPayDocument[]>;
+export function moveDocument(client: CoinPayClient, documentId: string, folder: string | null): Promise<{ folder: string | null }>;
+export function normalizeFolder(input: string | null | undefined): string | null;
+export function contentTypeFor(filename: string): string;
 export function getDocument(client: CoinPayClient, documentId: string): Promise<{ document: CoinPayDocument & { signed_available: boolean }; recipients: DocumentRecipient[]; events: unknown[]; versions: DocumentVersion[]; certificate: unknown }>;
 export function listDocumentVaults(client: CoinPayClient, opts?: { businessId?: string }): Promise<DocumentVault[]>;
 export function setupDocumentsVault(client: CoinPayClient, opts: { businessId: string; passphrase: string }): Promise<UnlockedVault>;
 export function unlockDocumentsVault(client: CoinPayClient, opts: { businessId: string; passphrase: string }): Promise<UnlockedVault>;
-export function uploadDocument(client: CoinPayClient, opts: { businessId: string; vault: UnlockedVault; bytes: Uint8Array; filename: string; title?: string; message?: string }): Promise<CoinPayDocument>;
+export function uploadDocument(client: CoinPayClient, opts: { businessId: string; vault: UnlockedVault; bytes: Uint8Array; filename: string; title?: string; message?: string; folder?: string | null }): Promise<CoinPayDocument>;
 export function shareDocument(
   client: CoinPayClient,
   documentId: string,

package/src/documents.js

@@ -38,6 +38,37 @@ export const DOCUMENT_TYPES = {
   pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
 };
 
+export const GENERIC_CONTENT_TYPE = 'application/octet-stream';
+export const MAX_DOCUMENT_BYTES = 9 * 1024 * 1024;
+
+/** Known types preview in the browser; anything else is an opaque download (it is ciphertext to the server). */
+export function contentTypeFor(filename) {
+  const name = String(filename);
+  const ext = name.includes('.') ? name.toLowerCase().split('.').pop() : '';
+  return DOCUMENT_TYPES[ext] ?? GENERIC_CONTENT_TYPE;
+}
+
+/** Same rules as the web app (src/lib/documents/types.ts): '/'-joined, no '.', '..' refused, null = top level. */
+export function normalizeFolder(input) {
+  if (input == null) return null;
+  const segments = String(input)
+    .split(/[\\/]+/)
+    // eslint-disable-next-line no-control-regex
+    .map((s) => s.replace(/[\u0000-\u001f\u007f]/g, '').trim())
+    .filter((s) => s && s !== '.');
+  if (segments.some((s) => s === '..')) throw new Error('Folder paths cannot contain ".."');
+  if (segments.length > 20) throw new Error('Folders can be at most 20 levels deep');
+  const joined = segments.map((s) => s.slice(0, 100)).join('/');
+  if (joined.length > 1000) throw new Error('Folder path is too long');
+  return joined || null;
+}
+
+export function isSkippedPath(relativePath) {
+  return String(relativePath)
+    .split(/[\\/]+/)
+    .some((s) => (s.startsWith('.') && s !== '.' && s !== '..') || s === 'node_modules' || s === 'Thumbs.db' || s === 'desktop.ini');
+}
+
 export const AAD = {
   original: (documentId) => `coinpay-doc:original:${documentId}`,
   version: (documentId, n) => (n === 1 ? `coinpay-doc:original:${documentId}` : `coinpay-doc:original:${documentId}:v${n}`),
@@ -122,8 +153,8 @@ export function linkWithKey(url, documentKey) {
 // API
 // ---------------------------------------------------------------------------
 
-export async function listDocuments(client, { businessId, status } = {}) {
-  const data = await client.request('/documents' + q({ business_id: businessId, status }));
+export async function listDocuments(client, { businessId, status, folder } = {}) {
+  const data = await client.request('/documents' + q({ business_id: businessId, status, folder }));
   return data.documents ?? [];
 }
 
@@ -168,10 +199,8 @@ async function documentKey(client, doc, vault) {
 }
 
 /** Encrypt and upload. `bytes` is the file content; `filename` decides its type. */
-export async function uploadDocument(client, { businessId, vault, bytes, filename, title, message }) {
-  const ext = String(filename).toLowerCase().split('.').pop();
-  const contentType = DOCUMENT_TYPES[ext];
-  if (!contentType) throw new Error('Unsupported file type: use ' + Object.keys(DOCUMENT_TYPES).join(', '));
+export async function uploadDocument(client, { businessId, vault, bytes, filename, title, message, folder }) {
+  const contentType = contentTypeFor(filename);
   const plain = new Uint8Array(bytes);
   const docId = globalThis.crypto.randomUUID();
   const dk = newKey();
@@ -180,6 +209,7 @@ export async function uploadDocument(client, { businessId, vault, bytes, filenam
     business_id: businessId,
     title: title || String(filename).replace(/\.[A-Za-z0-9]{1,5}$/, ''),
     message: message || null,
+    folder: normalizeFolder(folder),
     filename: String(filename).split(/[\\/]/).pop(),
     content_type: contentType,
     bytes: plain.length,
@@ -230,6 +260,11 @@ export async function voidDocument(client, documentId, { reason } = {}) {
   return client.request('/documents/' + id(documentId), json('PATCH', { action: 'void', ...(reason ? { reason } : {}) }));
 }
 
+/** File a document under another folder (null = top level). */
+export async function moveDocument(client, documentId, folder) {
+  return client.request('/documents/' + id(documentId), json('PATCH', { action: 'move', folder: normalizeFolder(folder) }));
+}
+
 export async function deleteDocument(client, documentId) {
   return client.request('/documents/' + id(documentId), { method: 'DELETE' });
 }
@@ -246,9 +281,7 @@ export async function listDocumentVersions(client, documentId) {
  */
 export async function uploadDocumentVersion(client, documentId, { vault, bytes, filename, note }) {
   const doc = (await getDocument(client, documentId)).document;
-  const ext = String(filename).toLowerCase().split('.').pop();
-  const contentType = DOCUMENT_TYPES[ext];
-  if (!contentType) throw new Error('Unsupported file type: use ' + Object.keys(DOCUMENT_TYPES).join(', '));
+  const contentType = contentTypeFor(filename);
   const dk = await documentKey(client, doc, vault);
   const plain = new Uint8Array(bytes);
   const next = doc.current_version + 1;

package/src/index.d.ts

@@ -129,7 +129,10 @@ export {
   downloadDocument,
   listDocumentVersions,
   uploadDocumentVersion,
+  moveDocument,
 } from './documents.js';
+export { publishDirectory, planPublish } from './documents-publish.js';
+export type { PublishEntry, PublishResult } from './documents-publish.js';
 export type { CoinPayDocument, DocumentRecipient, DocumentVault, DocumentVersion, UnlockedVault } from './documents.js';
 
 // Webhook exports

package/src/index.js

@@ -143,7 +143,9 @@ import {
   downloadDocument,
   listDocumentVersions,
   uploadDocumentVersion,
+  moveDocument,
 } from './documents.js';
+import { publishDirectory, planPublish } from './documents-publish.js';
 
 // Wallet exports
 import {
@@ -343,6 +345,9 @@ export {
   downloadDocument,
   listDocumentVersions,
   uploadDocumentVersion,
+  moveDocument,
+  publishDirectory,
+  planPublish,
   
   // Wallet
   WalletClient,