microsoft-graph-client 1.0.51 → 1.0.53

package/dist/utils/odata.js

@@ -19,9 +19,21 @@
  *      `?$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.
+ * **Build filter and search strings with the `odataFilter` / `odataSearch`
+ * tagged templates.** The tag applies the right layers to every interpolation,
+ * so the safe form is the default form instead of something each call site has
+ * to remember:
+ *
+ *     filters.push(odataFilter`from/emailAddress/address eq '${params.from}'`);
+ *
+ * Remembering to apply `odataFilterValue` by hand is exactly what let five call
+ * sites interpolate raw values for months. An untagged template
+ * literal that opens an OData string literal, or that reaches `.filter()` /
+ * `.search()` / `.query()` directly, is therefore an eslint error inside
+ * `src/api`.
+ *
+ * The value helpers below stay exported: they are what the tags are built from,
+ * and consumers of this package building their own queries need them.
  *
  * @see https://learn.microsoft.com/en-us/graph/filter-query-parameter
  */
@@ -29,8 +41,8 @@
  * 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.
+ * URL builder will handle URL encoding separately. In most cases, prefer the
+ * `odataFilter` tag, which combines both layers.
  *
  * @example
  * escapeODataLiteral("Let's Talk")  // → "Let''s Talk"
@@ -46,29 +58,133 @@ export function escapeODataLiteral(value) {
  *   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')
+ * Prefer the `odataFilter` tag inside this package; reach for this directly
+ * only when you are assembling a value away from the string it lands in.
  *
  * @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)
+ * odataFilterValue('invoice+statements@example.com');
+ * // → 'invoice%2Bstatements%40example.com'
+ * // Without the encoding, the SDK sends a raw `+`, which the server reads as
+ * // a space and the filter matches nobody.
  */
 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.
+ * Prepares a string for safe use as a `$search` value passed through the
+ * Microsoft Graph SDK's `.search()` builder.
+ *
+ * The SDK's `.search()` builder has the exact same non-encoding behavior as
+ * `.filter()` (see the module doc above) — it writes the value straight into
+ * `$search=...` on the request URL with no URL-encoding. `$search` values are
+ * plain quoted phrases, not OData string literals, so there's no literal
+ * layer to apply here (unlike `odataFilterValue`) — this is URL-encoding
+ * only.
+ *
+ * **It does not neutralize a literal `"` in the value.** The server percent-
+ * decodes `$search` before parsing it as KQL, so an embedded quote is restored
+ * and closes the phrase the caller wrapped around it. Verified against Graph:
+ * searching `Anthropic" OR from:someone@example.com` comes back as
+ * `Syntax error: character ':' is not valid at position 19 in
+ * '"Anthropic" OR from:someone@example.com"'` — the server quoting back the
+ * decoded string. That fails loud rather than mis-parsing silently, but a
+ * caller needing to search for a literal quote cannot express it here. What
+ * the encoding does buy is `+`, `&` and `#` surviving the URL.
+ *
+ * Prefer the `odataSearch` tag inside this package.
+ *
+ * @example
+ * odataSearchValue('from:invoice+statements@example.com');
+ * // → 'from%3Ainvoice%2Bstatements%40example.com'
+ */
+export function odataSearchValue(value) {
+    return encodeURIComponent(value);
+}
+/**
+ * An already-built OData fragment, interpolated into a tag verbatim.
+ *
+ * Produced only by {@link odataRaw}. Carrying a nominal type rather than a bare
+ * string is the point: the tags encode anything they are handed, and the only
+ * way past that is to say so explicitly at the call site.
+ */
+export class ODataRaw {
+    fragment;
+    constructor(fragment) {
+        this.fragment = fragment;
+    }
+}
+/**
+ * Marks an interpolation as OData *syntax* rather than a *value*, so the tags
+ * pass it through unencoded.
+ *
+ * This is the escape hatch, and it exists for one legitimate shape: composing
+ * clauses that the tags already built, where the parentheses, quotes and
+ * operators are structure and encoding them would destroy the expression.
+ *
+ * Never hand it something a caller supplied. If a value reaches `odataRaw`,
+ * the encoding is gone and nothing else will catch it.
+ *
+ * @example
+ * const clauses = addresses.map((a) => odataFilter`from/emailAddress/address eq '${a}'`);
+ * const anyOf = odataFilter`(${odataRaw(clauses.join(' or '))})`;
+ */
+export function odataRaw(fragment) {
+    return new ODataRaw(fragment);
+}
+function interpolate(strings, values, encode) {
+    let out = strings[0];
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        out += value instanceof ODataRaw ? value.fragment : encode(String(value));
+        out += strings[i + 1];
+    }
+    return out;
+}
+/**
+ * Builds an OData `$filter` expression, escaping and URL-encoding every
+ * interpolated value (see {@link odataFilterValue}).
  *
- * Kept temporarily for backwards compatibility with the old name.
+ * Write the OData syntax — including the quotes around a string literal — in
+ * the template; interpolate only values. Numbers, booleans and unquoted
+ * datetime literals are safe to interpolate as-is: encoding leaves them intact
+ * apart from characters that genuinely have to be encoded, such as the `+` in a
+ * timezone offset.
+ *
+ * @example
+ * odataFilter`from/emailAddress/address eq '${'invoice+statements@example.com'}'`;
+ * // → "from/emailAddress/address eq 'invoice%2Bstatements%40example.com'"
+ */
+export function odataFilter(strings, ...values) {
+    return interpolate(strings, values, odataFilterValue);
+}
+/**
+ * Builds an OData `$search` expression, URL-encoding every interpolated value
+ * (see {@link odataSearchValue}).
+ *
+ * Write the phrase quotes and any KQL operators in the template; interpolate
+ * only values.
+ *
+ * @example
+ * odataSearch`"mail:${'a+b@example.com'}" OR "displayName:${'a+b@example.com'}"`;
+ * // → '"mail:a%2Bb%40example.com" OR "displayName:a%2Bb%40example.com"'
+ */
+export function odataSearch(strings, ...values) {
+    return interpolate(strings, values, odataSearchValue);
+}
+/**
+ * Joins already-built clauses into an any-of group, parenthesised only when
+ * there is more than one.
+ *
+ * The parentheses matter: an `or` group spliced into a filter that also has
+ * `and` clauses would otherwise bind wrongly and widen the query instead of
+ * narrowing it. This exists so that composing clauses — the one legitimate use
+ * of {@link odataRaw} — has a name, rather than each new any-of filter reaching
+ * for the escape hatch and copying the last call site that did.
+ *
+ * @example
+ * odataAnyOf(addresses.map((a) => odataFilter`from/emailAddress/address eq '${a}'`));
  */
-export function escapeODataString(value) {
-    return escapeODataLiteral(value);
+export function odataAnyOf(clauses) {
+    return clauses.length === 1 ? clauses[0] : odataFilter `(${odataRaw(clauses.join(' or '))})`;
 }
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"odata.js","sourceRoot":"","sources":["../../src/utils/odata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,kBAAkB,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,QAAQ;IACgB;IAAnC,YAAmC,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;CACxD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAKD,SAAS,WAAW,CAClB,OAA6B,EAC7B,MAA4B,EAC5B,MAAiC;IAEjC,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,GAAG,IAAI,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1E,GAAG,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,OAA6B,EAAE,GAAG,MAA4B;IACxF,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,OAA6B,EAAE,GAAG,MAA4B;IACxF,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,OAAiB;IAC1C,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAA,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC;AAC9F,CAAC"}

package/dist/utils/retention.d.ts

@@ -0,0 +1,59 @@
+/** MAPI id of PR_POLICY_TAG — the retention tag GUID, stored as bytes. */
+export declare const RETENTION_TAG_PROPERTY = "Binary 0x3019";
+/** MAPI id of PR_RETENTION_PERIOD — days before the tag's action applies. */
+export declare const RETENTION_PERIOD_PROPERTY = "Integer 0x301A";
+/** MAPI id of PR_RETENTION_FLAGS — Exchange bookkeeping; read-only in practice. */
+export declare const RETENTION_FLAGS_PROPERTY = "Integer 0x301D";
+/** `$filter` selecting exactly the three retention properties in an `$expand`. */
+export declare const RETENTION_PROPERTY_FILTER: string;
+/** One entry of a `mailFolder`'s `singleValueExtendedProperties` collection, as Graph returns it. */
+export interface SingleValueExtendedProperty {
+    id?: string | null;
+    value?: string | null;
+}
+/** One entry as it is *sent* — a `null` value is the delete, so it is not optional. */
+export interface RetentionPropertyPayload {
+    id: string;
+    value: string | null;
+}
+/** A folder's retention policy, in the terms a person set it in. */
+export interface RetentionPolicy {
+    /** Retention tag GUID, in the form Exchange shows it. */
+    tag: string;
+    /** Days before the tag's action applies, when the folder carries one. */
+    periodDays: number | null;
+    /** Raw PR_RETENTION_FLAGS. Reported because it is there, not because it means anything. */
+    flags: number | null;
+}
+/**
+ * Decodes PR_POLICY_TAG's bytes into a GUID string.
+ *
+ * The bytes are in .NET `Guid` layout — the first three fields little-endian,
+ * the last two big-endian — not a flat big-endian read. Reading them flat
+ * produces a string that looks like a GUID and is not one: tags read off a real
+ * mailbox decode to a valid version-4 GUID under this layout, and to an
+ * impossible version nibble when the bytes are read straight through.
+ */
+export declare function decodeRetentionTag(base64Value: string): string | null;
+/** Encodes a GUID string back into PR_POLICY_TAG's bytes. Inverse of {@link decodeRetentionTag}. */
+export declare function encodeRetentionTag(guid: string): string;
+/**
+ * Reads a folder's retention policy out of its expanded extended properties.
+ *
+ * Returns `null` when the folder carries no tag. A folder whose policy has been
+ * cleared keeps a `PR_RETENTION_FLAGS` of 128, so presence of the properties is
+ * not the test — presence of a tag is.
+ */
+export declare function parseRetentionPolicy(properties: SingleValueExtendedProperty[] | null | undefined): RetentionPolicy | null;
+/**
+ * Builds the `singleValueExtendedProperties` payload for a PATCH.
+ *
+ * Pass a tag and period to assign a policy, or `null` for both to clear one.
+ * `PR_RETENTION_FLAGS` is only ever sent as `null`, on a clear: Exchange owns
+ * that value and rewrites whatever is sent.
+ */
+export declare function buildRetentionProperties(policy: {
+    tag: string | null;
+    periodDays: number | null;
+}): RetentionPropertyPayload[];
+//# sourceMappingURL=retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/utils/retention.ts"],"names":[],"mappings":"AA6BA,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAC1D,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,QAUvB,CAAC;AAEhB,qGAAqG;AACrG,MAAM,WAAW,2BAA2B;IAC1C,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,2BAA2B,EAAE,GAAG,IAAI,GAAG,SAAS,GAC3D,eAAe,GAAG,IAAI,CAsBxB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,wBAAwB,EAAE,CAiB7B"}

package/dist/utils/retention.js

@@ -0,0 +1,132 @@
+/**
+ * Mail folder retention policies — Outlook's "Assign Policy".
+ *
+ * There is no `retentionPolicy` property on `mailFolder`. The policy lives in
+ * three MAPI properties reachable through the `singleValueExtendedProperties`
+ * navigation property, which is why a scan of the declared `<Property>` list in
+ * `$metadata` concludes the feature is missing:
+ *
+ *   PR_POLICY_TAG       `Binary 0x3019`   the retention tag, a GUID in bytes
+ *   PR_RETENTION_PERIOD `Integer 0x301A`  days before the tag's action applies
+ *   PR_RETENTION_FLAGS  `Integer 0x301D`  Exchange's own bookkeeping
+ *
+ * Three behaviours verified against a live mailbox, each of which shapes the
+ * code below:
+ *
+ *   - **Flags do not round-trip.** Write 9, read back 137: Exchange ORs in 128
+ *     (NeedsRescan) itself. Never assert on them, and never send them back.
+ *   - **Clearing works only with `value: null`.** An empty string is stored as
+ *     an empty string, so the property survives and the folder still looks
+ *     policed. After a clear, `PR_RETENTION_FLAGS` is left behind as 128, so a
+ *     folder is "policed" when it has a tag, not when it has any of the three.
+ *   - **An invented tag GUID is accepted silently.** The PATCH succeeds, the
+ *     value reads back perfectly, and the Managed Folder Assistant then ignores
+ *     it forever. Every observable signal says a dead policy is live, which is
+ *     why callers must validate a tag against the ones a mailbox actually uses
+ *     rather than trusting a successful write.
+ */
+import { odataFilter, odataRaw } from './odata.js';
+/** MAPI id of PR_POLICY_TAG — the retention tag GUID, stored as bytes. */
+export const RETENTION_TAG_PROPERTY = 'Binary 0x3019';
+/** MAPI id of PR_RETENTION_PERIOD — days before the tag's action applies. */
+export const RETENTION_PERIOD_PROPERTY = 'Integer 0x301A';
+/** MAPI id of PR_RETENTION_FLAGS — Exchange bookkeeping; read-only in practice. */
+export const RETENTION_FLAGS_PROPERTY = 'Integer 0x301D';
+/** `$filter` selecting exactly the three retention properties in an `$expand`. */
+export const RETENTION_PROPERTY_FILTER = [RETENTION_TAG_PROPERTY, RETENTION_PERIOD_PROPERTY, RETENTION_FLAGS_PROPERTY]
+    // odataRaw because these are our own constants, not caller values: encoding
+    // them would send `Binary%200x3019`, which matches no property. Going through
+    // the tag anyway keeps the last hand-built OData string out of the package
+    // that exists to stop hand-built OData strings.
+    //
+    // Joined rather than composed with odataAnyOf: this sits inside
+    // `$expand=singleValueExtendedProperties($filter=…)`, where the parentheses
+    // odataAnyOf adds would be a change to a request that already works.
+    .map((id) => odataFilter `id eq '${odataRaw(id)}'`)
+    .join(' or ');
+const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Decodes PR_POLICY_TAG's bytes into a GUID string.
+ *
+ * The bytes are in .NET `Guid` layout — the first three fields little-endian,
+ * the last two big-endian — not a flat big-endian read. Reading them flat
+ * produces a string that looks like a GUID and is not one: tags read off a real
+ * mailbox decode to a valid version-4 GUID under this layout, and to an
+ * impossible version nibble when the bytes are read straight through.
+ */
+export function decodeRetentionTag(base64Value) {
+    const bytes = Buffer.from(base64Value, 'base64');
+    if (bytes.length !== 16)
+        return null;
+    // `bytes` is freshly allocated per call, so reversing sub-ranges in place is
+    // contained, and each range is reversed exactly once.
+    const hex = (start, end, littleEndian) => (littleEndian ? bytes.subarray(start, end).reverse() : bytes.subarray(start, end)).toString('hex');
+    return [hex(0, 4, true), hex(4, 6, true), hex(6, 8, true), hex(8, 10, false), hex(10, 16, false)].join('-');
+}
+/** Encodes a GUID string back into PR_POLICY_TAG's bytes. Inverse of {@link decodeRetentionTag}. */
+export function encodeRetentionTag(guid) {
+    if (!GUID_PATTERN.test(guid)) {
+        throw new Error(`Not a GUID: "${guid}". A retention tag is a GUID, e.g. 1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d.`);
+    }
+    const bytes = Buffer.from(guid.replace(/-/g, ''), 'hex');
+    // The first three fields are little-endian; the last two are already in order.
+    bytes.subarray(0, 4).reverse();
+    bytes.subarray(4, 6).reverse();
+    bytes.subarray(6, 8).reverse();
+    return bytes.toString('base64');
+}
+/**
+ * Reads a folder's retention policy out of its expanded extended properties.
+ *
+ * Returns `null` when the folder carries no tag. A folder whose policy has been
+ * cleared keeps a `PR_RETENTION_FLAGS` of 128, so presence of the properties is
+ * not the test — presence of a tag is.
+ */
+export function parseRetentionPolicy(properties) {
+    if (!properties?.length)
+        return null;
+    // Graph lowercases the hex in the ids it returns (`Integer 0x301a`), so match
+    // case-insensitively rather than against the constants verbatim.
+    const find = (id) => {
+        const wanted = id.toLowerCase();
+        return properties.find((p) => p.id?.toLowerCase() === wanted)?.value ?? null;
+    };
+    const rawTag = find(RETENTION_TAG_PROPERTY);
+    if (!rawTag)
+        return null;
+    const tag = decodeRetentionTag(rawTag);
+    if (!tag)
+        return null;
+    const toInt = (value) => {
+        if (value === null || value === '')
+            return null;
+        const n = Number.parseInt(value, 10);
+        return Number.isNaN(n) ? null : n;
+    };
+    return { tag, periodDays: toInt(find(RETENTION_PERIOD_PROPERTY)), flags: toInt(find(RETENTION_FLAGS_PROPERTY)) };
+}
+/**
+ * Builds the `singleValueExtendedProperties` payload for a PATCH.
+ *
+ * Pass a tag and period to assign a policy, or `null` for both to clear one.
+ * `PR_RETENTION_FLAGS` is only ever sent as `null`, on a clear: Exchange owns
+ * that value and rewrites whatever is sent.
+ */
+export function buildRetentionProperties(policy) {
+    if (policy.tag === null) {
+        return [
+            { id: RETENTION_TAG_PROPERTY, value: null },
+            { id: RETENTION_PERIOD_PROPERTY, value: null },
+            { id: RETENTION_FLAGS_PROPERTY, value: null },
+        ];
+    }
+    return [
+        { id: RETENTION_TAG_PROPERTY, value: encodeRetentionTag(policy.tag) },
+        // Always sent, `null` included. Omitting it leaves whatever period the
+        // previous policy wrote, so assigning a "delete after 7 days" tag to a
+        // folder that carried a 30-day one would produce a folder reporting the new
+        // tag with the old period — a mismatch every read reports as intentional.
+        { id: RETENTION_PERIOD_PROPERTY, value: policy.periodDays === null ? null : String(policy.periodDays) },
+    ];
+}
+//# sourceMappingURL=retention.js.map

package/dist/utils/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/utils/retention.ts"],"names":[],"mappings":"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"}

package/package.json

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