feat(telemetry): adding telemetry endpoints

openapi.json

@@ -67,6 +67,9 @@
     },
     {
       "name": "Deprecated"
+    },
+    {
+      "name": "Telemetry"
     }
   ],
   "components": {
@@ -34752,6 +34755,8 @@
                         "security-policy:read",
                         "socket-basics",
                         "socket-basics:read",
+                        "telemetry-policy",
+                        "telemetry-policy:update",
                         "threat-feed",
                         "threat-feed:list",
                         "triage",
@@ -35106,6 +35111,8 @@
                                 "security-policy:read",
                                 "socket-basics",
                                 "socket-basics:read",
+                                "telemetry-policy",
+                                "telemetry-policy:update",
                                 "threat-feed",
                                 "threat-feed:list",
                                 "triage",
@@ -35277,6 +35284,8 @@
                         "security-policy:read",
                         "socket-basics",
                         "socket-basics:read",
+                        "telemetry-policy",
+                        "telemetry-policy:update",
                         "threat-feed",
                         "threat-feed:list",
                         "triage",
@@ -37338,6 +37347,185 @@
         "x-readme": {}
       }
     },
+    "/orgs/{org_slug}/telemetry/config": {
+      "get": {
+        "tags": [
+          "Telemetry"
+        ],
+        "summary": "Get Organization Telemetry Config",
+        "operationId": "getOrgTelemetryConfig",
+        "parameters": [
+          {
+            "name": "org_slug",
+            "in": "path",
+            "required": true,
+            "description": "The slug of the organization",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "basicAuth": []
+          }
+        ],
+        "description": "Retrieve the telemetry config of an organization.\n\nThis endpoint consumes 1 unit of your quota.\n\nThis endpoint requires the following org token scopes:",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "description": "",
+                  "properties": {
+                    "telemetry": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "description": "Telemetry configuration",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "default": false,
+                          "description": "Telemetry enabled"
+                        }
+                      },
+                      "required": [
+                        "enabled"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "telemetry"
+                  ]
+                }
+              }
+            },
+            "description": "Retrieved telemetry config details"
+          },
+          "400": {
+            "$ref": "#/components/responses/SocketBadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/SocketUnauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/SocketForbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/SocketNotFoundResponse"
+          },
+          "429": {
+            "$ref": "#/components/responses/SocketTooManyRequestsResponse"
+          }
+        },
+        "x-readme": {}
+      },
+      "put": {
+        "tags": [
+          "Telemetry"
+        ],
+        "summary": "Update Telemetry Config",
+        "operationId": "updateOrgTelemetryConfig",
+        "parameters": [
+          {
+            "name": "org_slug",
+            "in": "path",
+            "required": true,
+            "description": "The slug of the organization",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Telemetry enabled"
+                  }
+                },
+                "description": ""
+              }
+            }
+          },
+          "required": false
+        },
+        "security": [
+          {
+            "bearerAuth": [
+              "telemetry-policy:update"
+            ]
+          },
+          {
+            "basicAuth": [
+              "telemetry-policy:update"
+            ]
+          }
+        ],
+        "description": "Update the telemetry config of an organization.\n\nThis endpoint consumes 1 unit of your quota.\n\nThis endpoint requires the following org token scopes:\n- telemetry-policy:update",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "description": "",
+                  "properties": {
+                    "telemetry": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "description": "Telemetry configuration",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "default": false,
+                          "description": "Telemetry enabled"
+                        }
+                      },
+                      "required": [
+                        "enabled"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "telemetry"
+                  ]
+                }
+              }
+            },
+            "description": "Updated telemetry config details"
+          },
+          "400": {
+            "$ref": "#/components/responses/SocketBadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/SocketUnauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/SocketForbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/SocketNotFoundResponse"
+          },
+          "429": {
+            "$ref": "#/components/responses/SocketTooManyRequestsResponse"
+          }
+        },
+        "x-readme": {}
+      }
+    },
     "/orgs/{org_slug}/webhooks": {
       "get": {
         "tags": [

src/index.ts

@@ -74,6 +74,9 @@ export type {
   PatchFile,
   PatchRecord,
   PatchViewResponse,
+  TelemetryConfig,
+  PostOrgTelemetryPayload,
+  PostOrgTelemetryResponse,
   QueryParams,
   RequestInfo,
   RequestOptions,

src/socket-sdk-class.ts

@@ -73,6 +73,8 @@ import type {
   GetOptions,
   GotOptions,
   PatchViewResponse,
+  PostOrgTelemetryPayload,
+  PostOrgTelemetryResponse,
   QueryParams,
   RequestOptions,
   SendOptions,
@@ -3481,6 +3483,113 @@ export class SocketSdk {
         })
     })
   }
+
+  /**
+   * Update organization's telemetry configuration.
+   * Enables or disables telemetry for the organization.
+   *
+   * @param orgSlug - Organization identifier
+   * @param telemetryData - Telemetry configuration with enabled flag
+   * @returns Updated telemetry configuration
+   *
+   * @throws {Error} When server returns 5xx status codes
+   */
+  async updateOrgTelemetryConfig(
+    orgSlug: string,
+    telemetryData: { enabled?: boolean | undefined },
+  ): Promise<SocketSdkResult<'updateOrgTelemetryConfig'>> {
+    try {
+      const data = await this.#executeWithRetry(
+        async () =>
+          await getResponseJson(
+            await createRequestWithJson(
+              'PUT',
+              this.#baseUrl,
+              `orgs/${encodeURIComponent(orgSlug)}/telemetry/config`,
+              telemetryData,
+              this.#reqOptions,
+            ),
+          ),
+      )
+      return this.#handleApiSuccess<'updateOrgTelemetryConfig'>(data)
+      /* c8 ignore start - Standard API error handling, tested via public method error cases */
+    } catch (e) {
+      return await this.#handleApiError<'updateOrgTelemetryConfig'>(e)
+    }
+    /* c8 ignore stop */
+  }
+
+  /**
+   * Get organization's telemetry configuration.
+   * Returns whether telemetry is enabled for the organization.
+   *
+   * @param orgSlug - Organization identifier
+   * @returns Telemetry configuration with enabled status
+   *
+   * @throws {Error} When server returns 5xx status codes
+   */
+  async getTelemetryConfig(
+    orgSlug: string,
+  ): Promise<SocketSdkResult<'getOrgTelemetryConfig'>> {
+    try {
+      const data = await this.#executeWithRetry(
+        async () =>
+          await getResponseJson(
+            await createGetRequest(
+              this.#baseUrl,
+              `orgs/${encodeURIComponent(orgSlug)}/telemetry/config`,
+              this.#reqOptions,
+            ),
+          ),
+      )
+      return this.#handleApiSuccess<'getOrgTelemetryConfig'>(data)
+      /* c8 ignore start - Standard API error handling, tested via public method error cases */
+    } catch (e) {
+      return await this.#handleApiError<'getOrgTelemetryConfig'>(e)
+    }
+    /* c8 ignore stop */
+  }
+
+  /**
+   * Post telemetry data for an organization.
+   * Sends telemetry events and analytics data for monitoring and analysis.
+   *
+   * @param orgSlug - Organization identifier
+   * @param telemetryData - Telemetry payload containing events and metrics
+   * @returns Empty object on successful submission
+   *
+   * @throws {Error} When server returns 5xx status codes
+   */
+  async postOrgTelemetry(
+    orgSlug: string,
+    telemetryData: PostOrgTelemetryPayload,
+  ): Promise<SocketSdkGenericResult<PostOrgTelemetryResponse>> {
+    try {
+      const data = (await this.#executeWithRetry(
+        async () =>
+          await getResponseJson(
+            await createRequestWithJson(
+              'POST',
+              this.#baseUrl,
+              `orgs/${encodeURIComponent(orgSlug)}/telemetry`,
+              telemetryData,
+              this.#reqOptions,
+            ),
+          ),
+      )) as PostOrgTelemetryResponse
+      return {
+        cause: undefined,
+        data,
+        error: undefined,
+        status: 200,
+        success: true,
+      }
+      /* c8 ignore start - Standard API error handling, tested via public method error cases */
+    } catch (e) {
+      return this.#createQueryErrorResult<PostOrgTelemetryResponse>(e)
+    }
+    /* c8 ignore stop */
+  }
 }
 
 // Optional live heap trace.

src/types.ts

@@ -423,6 +423,20 @@ export type StreamOrgFullScanOptions = {
   output?: boolean | string | undefined
 }
 
+export type PostOrgTelemetryPayload = Record<string, unknown>
+
+export type PostOrgTelemetryResponse = Record<string, never>
+
+/**
+ * Configuration for telemetry collection.
+ * Controls whether telemetry is enabled and how events are collected.
+ */
+export interface TelemetryConfig {
+  telemetry: {
+    enabled: boolean
+  }
+}
+
 export type UploadManifestFilesOptions = {
   pathsRelativeTo?: string | undefined
 }