microsoft-graph-client 1.0.33 → 1.0.34

package/dist/utils/odata.d.ts

@@ -1,17 +1,68 @@
 /**
- * Utilities for working with OData queries
+ * Utilities for building OData query parameter values that the Microsoft Graph
+ * SDK won't mangle.
+ *
+ * There are TWO distinct escaping layers when you put a user-supplied string
+ * inside an OData filter clause that gets sent to Graph as a query parameter:
+ *
+ *   1. OData literal escaping — single quotes inside a string literal must be
+ *      doubled, otherwise the OData parser breaks. This is `escapeODataLiteral`.
+ *
+ *   2. URL encoding of reserved characters — the Microsoft Graph SDK's
+ *      `.filter()` and `.query()` builders DO NOT URL-encode the *value* of
+ *      query parameters. As a result, characters like `&`, `+`, `#`, `?` get
+ *      passed through verbatim and break the URL parsing on the server side.
+ *
+ *      Empirically verified 2026-04-07: a topic filter for `'fm & fd'` failed
+ *      with `Invalid filter clause: There is an unterminated string literal at
+ *      position 28 in 'contains(tolower(topic), 'fm'.` because the SDK sent
+ *      `?$filter=...'fm & fd'...` and the server parsed the `&` as a query
+ *      param separator. See test/probe-encoding.mts for the verification.
+ *
+ * Use `escapeODataLiteral` when you control the URL building yourself (rare).
+ * Use `odataFilterValue` when you're going through the SDK's `.filter()` /
+ * `.query()` methods, which is what every API class in this package does.
+ *
+ * @see https://learn.microsoft.com/en-us/graph/filter-query-parameter
+ */
+/**
+ * Escapes single quotes in an OData string literal.
+ *
+ * Use this only if you are constructing a fully-formed URL yourself and your
+ * URL builder will handle URL encoding separately. In most cases, prefer
+ * `odataFilterValue` which combines both layers.
+ *
+ * @example
+ * escapeODataLiteral("Let's Talk")  // → "Let''s Talk"
  */
+export declare function escapeODataLiteral(value: string): string;
 /**
- * Escapes a string for use in OData filter expressions.
- * Single quotes are escaped by doubling them (' → '').
+ * Prepares a string for safe use as an OData filter value passed through the
+ * Microsoft Graph SDK's `.filter()` builder.
+ *
+ * Applies BOTH escaping layers:
+ *   1. OData literal escape (`'` → `''`)
+ *   2. URL-encode the result so reserved characters don't break the request URL
  *
- * @param value - The string to escape
- * @returns The escaped string safe for OData filters
+ * @example
+ * // Building a topic filter:
+ * const value = odataFilterValue("FM & FD");
+ * client.api('/me/chats').filter(`contains(tolower(topic), '${value}')`).get();
+ * // The SDK sends: ?$filter=contains(tolower(topic), 'fm%20%26%20fd')
  *
  * @example
- * // "Let's Talk" → "Let''s Talk"
- * const escaped = escapeODataString("Let's Talk");
- * const filter = `contains(topic, '${escaped}')`;
+ * // Filtering by a name with an apostrophe:
+ * const value = odataFilterValue("O'Brien");
+ * client.api('/me/chats').filter(`contains(displayName, '${value}')`).get();
+ * // → 'O%27%27Brien' (literal escape gives O''Brien, URL encode gives O%27%27Brien)
+ */
+export declare function odataFilterValue(value: string): string;
+/**
+ * @deprecated Use `escapeODataLiteral` (same behavior) for the literal escape,
+ * or `odataFilterValue` for the combined literal-escape + URL-encode that you
+ * almost always want when going through the Graph SDK builders.
+ *
+ * Kept temporarily for backwards compatibility with the old name.
  */
 export declare function escapeODataString(value: string): string;
 //# sourceMappingURL=odata.d.ts.map

package/dist/utils/odata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"odata.d.ts","sourceRoot":"","sources":["../../src/utils/odata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"odata.d.ts","sourceRoot":"","sources":["../../src/utils/odata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/utils/odata.js

@@ -1,19 +1,74 @@
 /**
- * Utilities for working with OData queries
+ * Utilities for building OData query parameter values that the Microsoft Graph
+ * SDK won't mangle.
+ *
+ * There are TWO distinct escaping layers when you put a user-supplied string
+ * inside an OData filter clause that gets sent to Graph as a query parameter:
+ *
+ *   1. OData literal escaping — single quotes inside a string literal must be
+ *      doubled, otherwise the OData parser breaks. This is `escapeODataLiteral`.
+ *
+ *   2. URL encoding of reserved characters — the Microsoft Graph SDK's
+ *      `.filter()` and `.query()` builders DO NOT URL-encode the *value* of
+ *      query parameters. As a result, characters like `&`, `+`, `#`, `?` get
+ *      passed through verbatim and break the URL parsing on the server side.
+ *
+ *      Empirically verified 2026-04-07: a topic filter for `'fm & fd'` failed
+ *      with `Invalid filter clause: There is an unterminated string literal at
+ *      position 28 in 'contains(tolower(topic), 'fm'.` because the SDK sent
+ *      `?$filter=...'fm & fd'...` and the server parsed the `&` as a query
+ *      param separator. See test/probe-encoding.mts for the verification.
+ *
+ * Use `escapeODataLiteral` when you control the URL building yourself (rare).
+ * Use `odataFilterValue` when you're going through the SDK's `.filter()` /
+ * `.query()` methods, which is what every API class in this package does.
+ *
+ * @see https://learn.microsoft.com/en-us/graph/filter-query-parameter
  */
 /**
- * Escapes a string for use in OData filter expressions.
- * Single quotes are escaped by doubling them (' → '').
+ * Escapes single quotes in an OData string literal.
  *
- * @param value - The string to escape
- * @returns The escaped string safe for OData filters
+ * Use this only if you are constructing a fully-formed URL yourself and your
+ * URL builder will handle URL encoding separately. In most cases, prefer
+ * `odataFilterValue` which combines both layers.
  *
  * @example
- * // "Let's Talk" → "Let''s Talk"
- * const escaped = escapeODataString("Let's Talk");
- * const filter = `contains(topic, '${escaped}')`;
+ * escapeODataLiteral("Let's Talk")  // → "Let''s Talk"
  */
-export function escapeODataString(value) {
+export function escapeODataLiteral(value) {
     return value.replace(/'/g, "''");
 }
+/**
+ * Prepares a string for safe use as an OData filter value passed through the
+ * Microsoft Graph SDK's `.filter()` builder.
+ *
+ * Applies BOTH escaping layers:
+ *   1. OData literal escape (`'` → `''`)
+ *   2. URL-encode the result so reserved characters don't break the request URL
+ *
+ * @example
+ * // Building a topic filter:
+ * const value = odataFilterValue("FM & FD");
+ * client.api('/me/chats').filter(`contains(tolower(topic), '${value}')`).get();
+ * // The SDK sends: ?$filter=contains(tolower(topic), 'fm%20%26%20fd')
+ *
+ * @example
+ * // Filtering by a name with an apostrophe:
+ * const value = odataFilterValue("O'Brien");
+ * client.api('/me/chats').filter(`contains(displayName, '${value}')`).get();
+ * // → 'O%27%27Brien' (literal escape gives O''Brien, URL encode gives O%27%27Brien)
+ */
+export function odataFilterValue(value) {
+    return encodeURIComponent(escapeODataLiteral(value));
+}
+/**
+ * @deprecated Use `escapeODataLiteral` (same behavior) for the literal escape,
+ * or `odataFilterValue` for the combined literal-escape + URL-encode that you
+ * almost always want when going through the Graph SDK builders.
+ *
+ * Kept temporarily for backwards compatibility with the old name.
+ */
+export function escapeODataString(value) {
+    return escapeODataLiteral(value);
+}
 //# sourceMappingURL=odata.js.map

package/dist/utils/odata.js.map

@@ -1 +1 @@
-{"version":3,"file":"odata.js","sourceRoot":"","sources":["../../src/utils/odata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"odata.js","sourceRoot":"","sources":["../../src/utils/odata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,kBAAkB,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "microsoft-graph-client",
-  "version": "1.0.33",
+  "version": "1.0.34",
   "publish": true,
   "description": "TypeScript client library for Microsoft Graph API with built-in authentication",
   "type": "module",