files.com 1.1.743 → 1.1.745

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a422fb27c774606b951cf47d99d36f6480eab1489536c421ec5f9a805a1b477a
-  data.tar.gz: 32674edcd54f7a5a70e59a50a29cb500029b0400d29af20285ab6dbefd7bd1ba
+  metadata.gz: 76561ada788c8c00625ff151cad4800e0e9d8d6daf4acd434baa34b7d28be212
+  data.tar.gz: e063b0dcec5148771d97c8cca16cd090c307fff2b55a5c7cfa16942460ad9546
 SHA512:
-  metadata.gz: babbaee413ae863433f3f7276342383112da748360da76f7e2bc3c0883aaa82cba1e3987178ee224b5a27f38b32410bc5b0780980c3ab719c97cdfe1435a9fd2
-  data.tar.gz: '08c007519882b709a66584483fec546a5fb9533fae557d91b180c64f608dc72a9223dc8ad8111f6defccde00959109ce439f09d1f937b9a3d3c77fb6bde0594c'
+  metadata.gz: b4cf0e52efc0fe229a2564bd784c579b4220a69cef0a493d6e8acaf20a4084cad8d99ffa36e073ec01e73242939119ee6fc241316fde6c0c706df5cfda9fac2d
+  data.tar.gz: 5e6a9e900cb910d8a17218adc1ee61d2a7308b68620e9111bc8f1e424f3a0ba80c26d064617a8d840c63574ba5879444865dca534f318d67d7c339506576cff1

data/README.md

@@ -346,16 +346,16 @@ end
 
 ## Paths
 
-Working with paths in Files.com involves several important considerations. Understanding how path comparisons are applied helps developers ensure consistency and accuracy across all interactions with the platform.
+Files.com preserves the spelling of file and folder paths while comparing them using shared case and Unicode rules. Use the SDK comparison helpers when matching paths locally.
 <div></div>
 
 ### Capitalization
 
-Files.com compares paths in a **case-insensitive** manner. This means path segments are treated as equivalent regardless of letter casing.
+Files.com uses case-insensitive path matching based on its fixed Unicode comparison map.
 
-For example, all of the following resolve to the same internal path:
+For example, the following paths have the same comparison key:
 
-| Path Variant                          | Interpreted As              |
+| Path Variant                          | Comparison Key              |
 |---------------------------------------|------------------------------|
 | `Documents/Reports/Q1.pdf`            | `documents/reports/q1.pdf`  |
 | `documents/reports/q1.PDF`            | `documents/reports/q1.pdf`  |
@@ -370,32 +370,27 @@ See also: [Case Sensitivity Documentation](https://www.files.com/docs/files-and-
 
 ### Slashes
 
-All path parameters in Files.com (API, SDKs, CLI, automations, integrations) must **omit leading and trailing slashes**. Paths are always treated as **absolute and slash-delimited**, so only internal `/` separators are used and never at the start or end of the string.
+Use `/` between folder and file names, without leading or trailing slashes. SDK normalization helpers convert backslashes to `/`, remove duplicate separators, and discard exact `.` and `..` components. Discarding `..` leaves the preceding folder name intact.
 
-####  Path Slash Examples
-| Path                              | Valid? | Notes                         |
-|-----------------------------------|--------|-------------------------------|
-| `folder/subfolder/file.txt`       |   ✅   | Correct, internal separators only |
-| `/folder/subfolder/file.txt`      |   ❌   | Leading slash not allowed     |
-| `folder/subfolder/file.txt/`      |   ❌   | Trailing slash not allowed    |
-| `//folder//file.txt`              |   ❌   | Duplicate separators not allowed |
+| Input | Normalized path |
+|-------|-----------------|
+| `folder/subfolder/file.txt` | `folder/subfolder/file.txt` |
+| `/folder/subfolder/file.txt` | `folder/subfolder/file.txt` |
+| `folder/subfolder/file.txt/` | `folder/subfolder/file.txt` |
+| `//folder//file.txt` | `folder/file.txt` |
+| `folder/../file.txt` | `folder/file.txt` |
 
 <div></div>
 
-### Unicode Normalization
+### Unicode and Path Comparison
 
-Files.com normalizes all paths using [Unicode NFC (Normalization Form C)](https://www.unicode.org/reports/tr15/#Norm_Forms) before comparison. This ensures consistency across different representations of the same characters.
+Files.com compares paths using a fixed mapping shared by the server and SDKs. It treats case and many accent differences as equivalent: `Résumé.txt` and `resume.txt` identify the same file, as do `q` followed by a combining acute accent and `q`. The mapping also handles other equivalences, such as Hiragana and Katakana. Lowercasing or applying a standard Unicode normalization form alone does not reproduce these rules.
 
-For example, the following two paths are treated as equivalent after NFC normalization:
+SDK comparison helpers normalize path separators and dot segments, then apply the bundled [versioned comparison map](https://github.com/Files-com/files-sdk-javascript/blob/master/shared/path_comparison.json). The [shared examples](https://github.com/Files-com/files-sdk-javascript/blob/master/shared/comparison_examples.json) give exact comparison results for integrations that implement their own matching. The map uses hexadecimal Unicode scalar values as keys: a missing entry preserves the character, an empty replacement removes it, and other replacements may contain several characters. Apply each replacement once without normalizing or lowercasing the result again.
 
-| Input                                  | Normalized Form       |
-|----------------------------------------|------------------------|
-| `uploads/\u0065\u0301.txt`             | `uploads/é.txt`        |
-| `docs/Café/Report.txt`                 | `docs/Café/Report.txt` |
+Use comparison results only for matching. Send the original path spelling in API requests and preserve it for display and local filenames; comparison results can have a different spelling or length.
 
-- All input must be UTF‑8 encoded.
-- Precomposed and decomposed characters are unified.
-- This affects search, deduplication, and comparisons across SDKs.
+Trailing whitespace is significant for comparison. `report.txt` and `report.txt ` are different file paths, and SDK helpers preserve spaces, tabs, and newlines. Folder names cannot end in whitespace. See [Unicode Normalization](https://www.files.com/docs/files-and-folders/file-system-semantics/unicode-normalization) for the complete path rules.
 
 <div></div>
 

data/_VERSION

@@ -1 +1 @@
-1.1.743
+1.1.745

data/lib/files.com/api_client.rb

@@ -150,9 +150,10 @@ module Files
     def remote_request(method, url, headers = {}, body = nil)
       context = RequestLogContext.new
       context.method       = method
-      context.path         = url
+      context.path         = "[transfer]"
+      Util.log_debug("Transfer request", method: method, url: url)
 
-      execute_request_with_rescues(Files.base_url, context, skip_body_logging: true) do
+      execute_request_with_rescues(Files.base_url, context, skip_body_logging: true, is_transfer: true) do
         conn.run_request(method, url, body, headers) do |req|
           req.options.open_timeout = Files.open_timeout
           req.options.timeout = Files.read_timeout
@@ -215,7 +216,7 @@ module Files
       raise AuthenticationError, "The provided Session ID is invalid (it contains whitespace)"
     end
 
-    def execute_request_with_rescues(base_url, context, skip_body_logging: false)
+    def execute_request_with_rescues(base_url, context, skip_body_logging: false, is_transfer: false)
       num_retries = 0
       begin
         request_start = Time.now
@@ -240,14 +241,18 @@ module Files
           retry
         end
 
+        Util.log_debug("Transfer error details", error_message: e.message) if is_transfer
+
         case e
         when Faraday::ClientError, Faraday::ServerError
           if e.response and has_error_type?(e)
-            handle_error_response(e.response, error_context)
+            handle_error_response(e.response, error_context, is_transfer: is_transfer)
           else
-            handle_network_error(e, error_context, num_retries, base_url)
+            handle_network_error(e, error_context, num_retries, base_url, is_transfer: is_transfer)
           end
         else
+          raise e.exception("Transfer request failed (#{e.class})"), cause: nil if is_transfer
+
           raise
         end
       end
@@ -266,7 +271,7 @@ module Files
       str
     end
 
-    private def handle_error_response(http_resp, context)
+    private def handle_error_response(http_resp, context, is_transfer: false)
       begin
         resp = Response.from_faraday_hash(http_resp)
         error_data = resp.data[:error] || resp.data[:errors]
@@ -275,17 +280,22 @@ module Files
 
         raise Error, "Unknown error" unless error_data
       rescue JSON::ParserError, Error
+        raise APIError.new("Transfer request failed", http_status: http_resp[:status]), cause: nil if is_transfer
+
         raise general_api_error(http_resp[:status], http_resp[:body])
       end
 
-      error = specific_api_error(resp, error_data, context)
+      error = specific_api_error(resp, error_data, context, is_transfer: is_transfer)
 
       error.response = resp
-      raise(error)
+      raise error, cause: nil if is_transfer
+
+      raise error
     end
 
-    private def specific_api_error(resp, error_data, _context)
-      Util.log_error("API error", status: resp.http_status, error_message: error_data[:message])
+    private def specific_api_error(resp, error_data, _context, is_transfer: false)
+      message = is_transfer ? "Transfer request failed" : error_data[:message]
+      Util.log_error("API error", status: resp.http_status, error_message: message)
 
       opts = {
         http_body: resp.http_body,
@@ -295,28 +305,34 @@ module Files
         code: error_data[:code] || resp.http_status,
       }
 
-      return APIError.new(error_data[:message], **opts) unless resp&.data&.dig(:type)
+      return APIError.new(message, **opts) unless resp&.data&.dig(:type)
 
       begin
         error_type = resp.data[:type].split("/").last
         error_class_name = "#{error_type.split("-").map(&:capitalize).join}Error"
         error_class = Files.const_get(error_class_name)
-        error_class.new(error_data[:message], **opts)
+        error_class.new(message, **opts)
       rescue NameError
-        APIError.new(error_data[:message], **opts)
+        APIError.new(message, **opts)
       end
     end
 
-    private def handle_network_error(error, _context, num_retries, base_url = nil)
+    private def handle_network_error(error, _context, num_retries, base_url = nil, is_transfer: false)
       base_url ||= Files.base_url
 
-      error_message = error.message.empty? ? error.response[:body] : error.message
+      error_message = if is_transfer
+                        error.class.name
+                      else
+                        error.message.empty? ? error.response[:body] : error.message
+                      end
 
       Util.log_error("Network error", error_message: error_message)
       message = "Could not connect to Files.com at URL #{base_url}. Please check your internet connection and try again. If this problem persists, you should check Files.com's service status at https://status.files.com, or contact your primary account representative."
       message += " Request was retried #{num_retries} times." if num_retries > 0
       message += "\n\n(Network error: #{error_message})"
 
+      raise APIConnectionError, message, cause: nil if is_transfer
+
       raise APIConnectionError, message
     end
 
@@ -372,7 +388,8 @@ module Files
     end
 
     private def log_response_error(context, request_start, error)
-      Util.log_error("Error", elapsed: Time.now - request_start, error_message: error.message, method: context.method, path: context.path)
+      Util.log_error("Error", elapsed: Time.now - request_start, error_type: error.class, method: context.method, path: context.path)
+      Util.log_debug("Error details", error_message: error.message)
     end
 
     class RequestLogContext

data/lib/files.com/path_util.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Files
   module PathUtil
-    TRANSLIT_MAP = "ÀA,ÁA,ÂA,ÃA,ÄA,ÅA,ÆAE,ÇC,ÈE,ÉE,ÊE,ËE,ÌI,ÍI,ÎI,ÏI,ÐD,ÑN,ÒO,ÓO,ÔO,ÕO,ÖO,ØO,ÙU,ÚU,ÛU,ÜU,ÝY,ßss,àa,áa,âa,ãa,äa,åa,æae,çc,èe,ée,êe,ëe,ìi,íi,îi,ïi,ðd,ñn,òo,óo,ôo,õo,öo,øo,ùu,úu,ûu,üu,ýy,ÿy,ĀA,āa,ĂA,ăa,ĄA,ąa,ĆC,ćc,ĈC,ĉc,ĊC,ċc,ČC,čc,ĎD,ďd,ĐD,đd,ĒE,ēe,ĔE,ĕe,ĖE,ėe,ĘE,ęe,ĚE,ěe,ĜG,ĝg,ĞG,ğg,ĠG,ġg,ĢG,ģg,ĤH,ĥh,ĦH,ħh,ĨI,ĩi,ĪI,īi,ĬI,ĭi,ĮI,įi,İI,IJIJ,ijij,ĴJ,ĵj,ĶK,ķk,ĹL,ĺl,ĻL,ļl,ĽL,ľl,ŁL,łl,ŃN,ńn,ŅN,ņn,ŇN,ňn,ʼn'n,ŌO,ōo,ŎO,ŏo,ŐO,őo,ŒOE,œoe,ŔR,ŕr,ŖR,ŗr,ŘR,řr,ŚS,śs,ŜS,ŝs,ŞS,şs,ŠS,šs,ŢT,ţt,ŤT,ťt,ŨU,ũu,ŪU,ūu,ŬU,ŭu,ŮU,ůu,ŰU,űu,ŲU,ųu,ŴW,ŵw,ŶY,ŷy,ŸY,ŹZ,źz,ŻZ,żz,ŽZ,žz".split(",").to_h { |val| [ val[0], val[1..2] ] }.freeze
+    COMPARISON_MAP = JSON.parse(File.read(File.expand_path("../../shared/path_comparison.json", __dir__))).fetch("mapping").to_h { |hex, value| [ hex.to_i(16).chr(Encoding::UTF_8), value.freeze ] }.freeze
 
     def self.normalize_for_comparison(*args)
-      unicode_normalize_and_transliterate(normalize(*args).to_s).downcase.rstrip
+      normalize(*args).gsub(/[^ -@\[-~]/) { |character| COMPARISON_MAP.fetch(character, character) }
     end
 
     def self.same?(a, b)
@@ -39,14 +41,5 @@ module Files
         new_string.force_encoding("ISO-8859-1").encode("UTF-8")
       end
     end
-
-    private_class_method def self.unicode_normalize_and_transliterate(string)
-      # convert multi-code-point characters into single-code-point characters
-      normalized_string = string.unicode_normalize(:nfkc)
-
-      normalized_string.gsub(/[^\x00-\x7f]/u) do |char|
-        TRANSLIT_MAP[char] || char
-      end
-    end
   end
 end

data/lib/files.com/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Files
-  VERSION = "1.1.743"
+  VERSION = "1.1.745"
 end

data/shared/comparison_examples.json

@@ -0,0 +1,20 @@
+[
+  ["Résumé.TXT", "resume.txt"],
+  ["q́/ậ.txt", "q/a.txt"],
+  ["ς/Σ/ά", "σ/σ/α"],
+  ["か/カ/ガ", "か/か/か"],
+  ["private\u00ad\u200d\ufe0f/file", "private/file"],
+  ["\u0307", ""],
+  ["a\u0001b", "ab"],
+  ["folder \t", "folder \t"],
+  ["Ა/ა", "Ა/ა"],
+  ["\u09cb/\u09c7\u09be", "\u09cb/\u09c7\u09be"],
+  ["ка/का/क", "ка/का/क"],
+  ["й/и", "й/и"],
+  ["日本語", "日本語"],
+  ["가/가", "가/가"],
+  ["Ａ／Ｂ/℀/…", "a/b/a/c/..."],
+  ["𐐀/𐐨", "𐐨/𐐨"],
+  ["𠀀/𠀁", "𠀀/𠀁"],
+  ["ﷺ", "صلى الله"]
+]

data/shared/normalization_for_comparison_test_data.json

@@ -8,15 +8,15 @@
   [ "A\\B\\C.TXT", "a/b/c.txt" ],
   [ "A/B\\C.TXT", "a/b/c.txt" ],
   [ "//a/b//c.txt", "a/b/c.txt" ],
-  [ "a/b/c.txt  ", "a/b/c.txt" ],
-  [ "a/b/c.txt\t", "a/b/c.txt" ],
-  [ "a/b/c.txt\n", "a/b/c.txt" ],
-  [ "a/b/c.txt\r", "a/b/c.txt" ],
+  [ "a/b/c.txt  ", "a/b/c.txt  "],
+  [ "a/b/c.txt\t", "a/b/c.txt\t"],
+  [ "a/b/c.txt\n", "a/b/c.txt\n"],
+  [ "a/b/c.txt\r", "a/b/c.txt\r"],
   [ " space_at_beginning", " space_at_beginning"],
-  [ "space_at_end ", "space_at_end"],
+  [ "space_at_end ", "space_at_end "],
   [ "tab\tseparated", "tab\tseparated"],
   [ "<title>hello</hello>", "<title>hello</hello>"],
-  [ "안녕하세요", "안녕하세요" ],
+  [ "안녕하세요", "안녕하세요"],
   [ "こんにちは", "こんにちは" ],
   [ "今日は", "今日は" ],
   [ "longest_unicode_character_﷽", "longest_unicode_character_﷽"],
@@ -27,16 +27,16 @@
   [ "/../../remote\\path//./to/file.txt", "remote/path/to/file.txt" ],
   [ "one_code_point_ą", "one_code_point_a" ],
   [ "two_code_points_ą", "two_code_points_a" ],
-  [ "one_code_point_훯", "one_code_point_훯"],
-  [ "three_code_points_훯", "three_code_points_훯" ],
+  [ "one_code_point_훯", "one_code_point_훯"],
+  [ "three_code_points_훯", "three_code_points_훯"],
   [ "ÞþŊŋŦŧ", "þþŋŋŧŧ" ],
   [ "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýÿ", "aaaaaaaeceeeeiiiidnoooooouuuuyssaaaaaaaeceeeeiiiidnoooooouuuuyy" ],
   [ "ĀāĂ㥹ĆćĈĉĊċČčĎďĐđĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪīĬĭĮįİIJij", "aaaaaaccccccccddddeeeeeeeeeegggggggghhhhiiiiiiiiiijij" ],
   [ "ĴĵĶķĹĺĻļĽľŁłŃńŅņŇňʼnŌōŎŏŐőŒœŔŕŖŗŘřŚśŜŝŞşŠšŢţŤť", "jjkkllllllllnnnnnnʼnoooooooeoerrrrrrsssssssstttt" ],
   [ "ŨũŪūŬŭŮůŰűŲųŴŵŶŷŸŹźŻżŽž", "uuuuuuuuuuuuwwyyyzzzzzz" ],
-  [ "😂❤️😍🤣😊🙏💕😭😘👍😅👏😁♥️🔥💔💖💙😢🤔😆🙄💪😉☺️👌🤗", "😂❤️😍🤣😊🙏💕😭😘👍😅👏😁♥️🔥💔💖💙😢🤔😆🙄💪😉☺️👌🤗" ],
-  [ "💜😔😎😇🌹🤦🎉💞✌️✨🤷😱😌🌸🙌😋💗💚😏💛🙂💓🤩😄😀🖤😃💯🙈👇🎶😒🤭❣️", "💜😔😎😇🌹🤦🎉💞✌️✨🤷😱😌🌸🙌😋💗💚😏💛🙂💓🤩😄😀🖤😃💯🙈👇🎶😒🤭❣️" ],
-  [ "emoji_‼️", "emoji_!!️" ],
+  [ "😂❤️😍🤣😊🙏💕😭😘👍😅👏😁♥️🔥💔💖💙😢🤔😆🙄💪😉☺️👌🤗", "😂❤😍🤣😊🙏💕😭😘👍😅👏😁♥🔥💔💖💙😢🤔😆🙄💪😉☺👌🤗"],
+  [ "💜😔😎😇🌹🤦🎉💞✌️✨🤷😱😌🌸🙌😋💗💚😏💛🙂💓🤩😄😀🖤😃💯🙈👇🎶😒🤭❣️", "💜😔😎😇🌹🤦🎉💞✌✨🤷😱😌🌸🙌😋💗💚😏💛🙂💓🤩😄😀🖤😃💯🙈👇🎶😒🤭❣"],
+  [ "emoji_‼️", "emoji_!!"],
   [ "<title>hello<:hello>.txt", "<title>hello<:hello>.txt" ],
   [ "twodotfile..txt", "twodotfile..txt" ],
   [ "three/.../dots_path", "three/.../dots_path" ],