microsoft-graph-client 1.0.52 → 1.0.53

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.52",
+  "version": "1.0.53",
   "publish": true,
   "description": "TypeScript client library for Microsoft Graph API with built-in authentication",
   "type": "module",