Network Shares (SMB)

A Network Share data source connects ApiMeld to an SMB/CIFS file share. Scripts can list, read, write, move, and delete files — subject to the permissions of the configured share account — without embedding share paths or credentials directly in the script. Any SMB-compatible server works: Windows file shares, Samba, TrueNAS, OpenMediaVault, Synology, and similar NAS devices.

Setting up a network share data source

1. Go to Data Sources → New Data Source
2. Select Network Share
3. Fill in the connection details:

Field	Description
Name	How scripts reference this share (e.g. ReportsShare)
Host	Hostname or IP of the file server (e.g. fileserver or 192.168.1.10)
Share Name	The share name on the server (e.g. SharedDocs) — just the share, not the full UNC path
Base Path	Optional subfolder within the share to scope all operations (e.g. Reports/Incoming). Scripts cannot navigate above this path.
Domain	Optional Windows domain for NTLM authentication
Username / Password	Share credentials (password stored AES-256-GCM encrypted)

4. Click Test Connection to verify
5. Save

Base Path scoping

Setting a Base Path is recommended. It prevents scripts from accidentally reading or writing files outside the intended folder, and blocks path traversal attempts (..) at the server level.

Available methods

All paths passed to these methods are relative to the configured Base Path. Write operations (WriteFile, DeleteFile, MoveFile, Mkdir, Rmdir) will fail if the configured credentials only have read access on the share — what ApiMeld can do is limited by the permissions granted to the share account on the file server.

Method	Description
List(path?, pattern?)	List files and directories. Optional glob pattern (e.g. *.csv).
Exists(path)	Returns true if the file or directory exists.
ReadRaw(path)	Read file contents as a string.
ReadCsv(path, delimiter?)	Parse a CSV file and return an array of row objects. Delimiter defaults to ,.
ReadExcel(path, sheet?)	Parse an Excel file (.xlsx) and return an array of row objects. Defaults to first sheet.
TempPath(path)	Copy the file to a local temp path and return that path. Useful for tools that need a real file path.
WriteFile(path, content)	Write a string to a file (creates or overwrites).
DeleteFile(path)	Delete a file.
MoveFile(sourcePath, destPath)	Move or rename a file within the share.
Mkdir(path)	Create a directory.
Rmdir(path)	Remove a directory.

List() returns an array of objects with: name, isDirectory, sizeBytes, modifiedAt.

File reads are subject to a configurable size limit (default 25 MB). An admin can raise this under Admin → Settings → Storage.

PowerShell examples

# List all CSV files in the Incoming folder
$files = $datasources.ReportsShare.List("Incoming", "*.csv")
foreach ($f in $files) {
    $logger.Info("Found: $($f.name) ($($f.sizeBytes) bytes)")
}

# Read and parse a CSV
$rows = $datasources.ReportsShare.ReadCsv("Incoming/sales.csv")
$logger.Info("Row count: $($rows.Count)")

# Read an Excel file from a specific sheet
$data = $datasources.ReportsShare.ReadExcel("Incoming/report.xlsx", "Sheet2")

# Write a result file
$datasources.ReportsShare.WriteFile("Outgoing/summary.txt", "Total rows: $($rows.Count)")

# Move a processed file to an archive folder
$datasources.ReportsShare.MoveFile("Incoming/sales.csv", "Archive/sales_processed.csv")

# Use TempPath to pass a file to a PowerShell cmdlet that needs a real path
$localPath = $datasources.ReportsShare.TempPath("Incoming/data.xlsx")
Import-Excel -Path $localPath

JavaScript / TypeScript examples

// List all CSV files in the Incoming folder
const files = await datasources.ReportsShare.list('Incoming', '*.csv')
files.forEach(f => logger.info(`Found: ${f.name} (${f.sizeBytes} bytes)`))

// Read and parse a CSV
const rows = await datasources.ReportsShare.readCsv('Incoming/sales.csv')
logger.info(`Row count: ${rows.length}`)

// Read an Excel file from a specific sheet
const data = await datasources.ReportsShare.readExcel('Incoming/report.xlsx', 'Sheet2')

// Write a result file
await datasources.ReportsShare.writeFile('Outgoing/summary.txt', `Total rows: ${rows.length}`)

// Move a processed file to an archive folder
await datasources.ReportsShare.moveFile('Incoming/sales.csv', 'Archive/sales_processed.csv')

Common patterns

Process and archive files

$files = $datasources.ReportsShare.List("Incoming", "*.csv")

foreach ($f in $files) {
    $rows = $datasources.ReportsShare.ReadCsv("Incoming/$($f.name)")
    # ... process rows ...

    # Archive after processing
    $datasources.ReportsShare.MoveFile(
        "Incoming/$($f.name)",
        "Archive/$($f.name)"
    )
    $logger.Info("Processed and archived: $($f.name)")
}

Check for a file before reading

const path = 'Incoming/daily-export.csv'

if (await datasources.ReportsShare.exists(path)) {
  const rows = await datasources.ReportsShare.readCsv(path)
  logger.info(`Processing ${rows.length} rows`)
} else {
  logger.warn('Export file not found — skipping')
}