feat(cloudflare): Automatically set the release id when CF_VERSION_METADATA is enabled (#18855)

The `CF_VERSION_METADATA` only has one reason - to add the release id.

Since we already set the release when `SENTRY_RELEASE` is enabled
automatically, we can do the same for `CF_VERSION_METADATA`. The docs
will then also be updated to state how the release id can be set in
different ways: getsentry/sentry-docs#16006

Closes #18856 (added automatically)
Closes
[JS-1489](https://linear.app/getsentry/issue/JS-1489/featcloudflare-automatically-set-the-release-id-when-cf-version)

Author: JPeer264

packages/cloudflare/src/options.ts

@@ -1,9 +1,31 @@
 import type { CloudflareOptions } from './client';
 
+/**
+ * Cloudflare's version metadata binding structure.
+ * @see https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/
+ */
+interface CfVersionMetadata {
+  id: string;
+  tag?: string;
+  timestamp?: string;
+}
+
+/**
+ * Checks if the value is a valid CF_VERSION_METADATA binding.
+ */
+function isVersionMetadata(value: unknown): value is CfVersionMetadata {
+  return typeof value === 'object' && value !== null && 'id' in value && typeof value.id === 'string';
+}
+
 /**
  * Merges the options passed in from the user with the options we read from
  * the Cloudflare `env` environment variable object.
  *
+ * Release is determined with the following priority (highest to lowest):
+ * 1. User-provided release option
+ * 2. SENTRY_RELEASE environment variable
+ * 3. CF_VERSION_METADATA.id binding (if configured in the wrangler config)
+ *
  * @param userOptions - The options passed in from the user.
  * @param env - The environment variables.
  *
@@ -14,7 +36,13 @@ export function getFinalOptions(userOptions: CloudflareOptions, env: unknown): C
     return userOptions;
   }
 
-  const release = 'SENTRY_RELEASE' in env && typeof env.SENTRY_RELEASE === 'string' ? env.SENTRY_RELEASE : undefined;
+  // Priority: userOptions.release > SENTRY_RELEASE > CF_VERSION_METADATA.id
+  const release =
+    'SENTRY_RELEASE' in env && typeof env.SENTRY_RELEASE === 'string'
+      ? env.SENTRY_RELEASE
+      : 'CF_VERSION_METADATA' in env && isVersionMetadata(env.CF_VERSION_METADATA)
+        ? env.CF_VERSION_METADATA.id
+        : undefined;
 
   return { release, ...userOptions };
 }

packages/cloudflare/test/options.test.ts

@@ -55,4 +55,75 @@ describe('getFinalOptions', () => {
 
     expect(result).toEqual(userOptions);
   });
+
+  describe('CF_VERSION_METADATA', () => {
+    it('uses CF_VERSION_METADATA.id as release when no other release is set', () => {
+      const userOptions = { dsn: 'test-dsn' };
+      const env = { CF_VERSION_METADATA: { id: 'version-123', tag: 'v1.0.0' } };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: 'version-123' });
+    });
+
+    it('prefers SENTRY_RELEASE over CF_VERSION_METADATA.id', () => {
+      const userOptions = { dsn: 'test-dsn' };
+      const env = {
+        SENTRY_RELEASE: 'env-release',
+        CF_VERSION_METADATA: { id: 'version-123' },
+      };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: 'env-release' });
+    });
+
+    it('prefers user release over CF_VERSION_METADATA.id', () => {
+      const userOptions = { dsn: 'test-dsn', release: 'user-release' };
+      const env = { CF_VERSION_METADATA: { id: 'version-123' } };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: 'user-release' });
+    });
+
+    it('prefers user release over both SENTRY_RELEASE and CF_VERSION_METADATA.id', () => {
+      const userOptions = { dsn: 'test-dsn', release: 'user-release' };
+      const env = {
+        SENTRY_RELEASE: 'env-release',
+        CF_VERSION_METADATA: { id: 'version-123' },
+      };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: 'user-release' });
+    });
+
+    it('ignores CF_VERSION_METADATA when it is not an object', () => {
+      const userOptions = { dsn: 'test-dsn' };
+      const env = { CF_VERSION_METADATA: 'not-an-object' };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: undefined });
+    });
+
+    it('ignores CF_VERSION_METADATA when id is not a string', () => {
+      const userOptions = { dsn: 'test-dsn' };
+      const env = { CF_VERSION_METADATA: { id: 123 } };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: undefined });
+    });
+
+    it('ignores CF_VERSION_METADATA when id is missing', () => {
+      const userOptions = { dsn: 'test-dsn' };
+      const env = { CF_VERSION_METADATA: { tag: 'v1.0.0' } };
+
+      const result = getFinalOptions(userOptions, env);
+
+      expect(result).toEqual({ dsn: 'test-dsn', release: undefined });
+    });
+  });
 });