chore: Some improvements to @sentry/types

packages/tracing/src/spanstatus.ts

@@ -1,40 +1,98 @@
-/** The status of an Span. */
+/**
+ * Describes the status of the Span/Transaction.
+ */
 // eslint-disable-next-line import/export
 export enum SpanStatus {
-  /** The operation completed successfully. */
+  /**
+   * Not an error, returned on success
+   */
   Ok = 'ok',
-  /** Deadline expired before operation could complete. */
+
+  /**
+   * The operation was cancelled, typically by the caller
+   */
+  Cancelled = 'cancelled',
+
+  /** An unknown error raised by APIs that don't return enough error information. */
+  Unknown = 'unknown',
+
+  /**
+   * An unknown error raised by APIs that don't return enough error information.
+   */
+  UnknownError = 'unknown_error',
+
+  /**
+   * The client specified an invalid argument
+   */
+  InvalidArgument = 'invalid_argument',
+
+  /**
+   * The deadline expired before the operation could succeed.
+   */
   DeadlineExceeded = 'deadline_exceeded',
-  /** 401 Unauthorized (actually does mean unauthenticated according to RFC 7235) */
-  Unauthenticated = 'unauthenticated',
-  /** 403 Forbidden */
-  PermissionDenied = 'permission_denied',
-  /** 404 Not Found. Some requested entity (file or directory) was not found. */
+
+  /**
+   * Content was not found or request was denied for an entire class of users.
+   */
   NotFound = 'not_found',
-  /** 429 Too Many Requests */
-  ResourceExhausted = 'resource_exhausted',
-  /** Client specified an invalid argument. 4xx. */
-  InvalidArgument = 'invalid_argument',
-  /** 501 Not Implemented */
-  Unimplemented = 'unimplemented',
-  /** 503 Service Unavailable */
-  Unavailable = 'unavailable',
-  /** Other/generic 5xx. */
-  InternalError = 'internal_error',
-  /** Unknown. Any non-standard HTTP status code. */
-  UnknownError = 'unknown_error',
-  /** The operation was cancelled (typically by the user). */
-  Cancelled = 'cancelled',
-  /** Already exists (409) */
+
+  /**
+   * The entity attempted to be created already exists
+   */
   AlreadyExists = 'already_exists',
-  /** Operation was rejected because the system is not in a state required for the operation's */
+
+  /**
+   * The caller doesn't have permission to execute the specified operation.
+   */
+  PermissionDenied = 'permission_denied',
+
+  /**
+   * The resource has been exhausted e.g. per-user quota exhausted,
+   * file system out of space.
+   */
+  ResourceExhausted = 'resource_exhausted',
+
+  /**
+   * The client shouldn't retry until the system state has been explicitly handled.
+   */
   FailedPrecondition = 'failed_precondition',
-  /** The operation was aborted, typically due to a concurrency issue. */
+
+  /**
+   * The operation was aborted.
+   */
   Aborted = 'aborted',
-  /** Operation was attempted past the valid range. */
+
+  /**
+   * The operation was attempted past the valid range e.g.
+   * seeking past the end of a file.
+   */
   OutOfRange = 'out_of_range',
-  /** Unrecoverable data loss or corruption */
+
+  /**
+   * The operation is not implemented or is not supported/enabled for this operation.
+   */
+  Unimplemented = 'unimplemented',
+
+  /**
+   * Some invariants expected by the underlying system have been broken.
+   * This code is reserved for serious errors
+   */
+  InternalError = 'internal_error',
+
+  /**
+   * The service is currently available e.g. as a transient condition.
+   */
+  Unavailable = 'unavailable',
+
+  /**
+   * Unrecoverable data loss or corruption.
+   */
   DataLoss = 'data_loss',
+
+  /**
+   * The requester doesn't have valid authentication credentials for the operation.
+   */
+  Unauthenticated = 'unauthenticated',
 }
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
@@ -52,31 +110,43 @@ export namespace SpanStatus {
 
     if (httpStatus >= 400 && httpStatus < 500) {
       switch (httpStatus) {
-        case 401:
-          return SpanStatus.Unauthenticated;
-        case 403:
-          return SpanStatus.PermissionDenied;
+        case 499:
+          return SpanStatus.Cancelled;
+        case 400:
+          return SpanStatus.InvalidArgument;
+        // Could be as well
+        // return SpanStatus.FailedPrecondition;
+        // return SpanStatus.OutOfRange;
         case 404:
           return SpanStatus.NotFound;
         case 409:
           return SpanStatus.AlreadyExists;
-        case 413:
-          return SpanStatus.FailedPrecondition;
+        // Could be as well
+        // return SpanStatus.Aborted;
+        case 403:
+          return SpanStatus.PermissionDenied;
         case 429:
           return SpanStatus.ResourceExhausted;
+        case 401:
+          return SpanStatus.Unauthenticated;
         default:
           return SpanStatus.InvalidArgument;
       }
     }
 
     if (httpStatus >= 500 && httpStatus < 600) {
       switch (httpStatus) {
+        case 500:
+          return SpanStatus.InternalError;
+        // Could be as well
+        // return SpanStatus.UnknownError;
+        // return SpanStatus.DataLoss;
+        case 504:
+          return SpanStatus.DeadlineExceeded;
         case 501:
           return SpanStatus.Unimplemented;
         case 503:
           return SpanStatus.Unavailable;
-        case 504:
-          return SpanStatus.DeadlineExceeded;
         default:
           return SpanStatus.InternalError;
       }

packages/types/src/appcontext.ts

@@ -0,0 +1,43 @@
+import { Context } from './context';
+
+/**
+ * App context describes the application. As opposed to the runtime,
+ * this is the actual application that was running and carries metadata about the current session.
+ * @external https://develop.sentry.dev/sdk/event-payloads/contexts/#app-context
+ */
+export interface AppContext extends Context {
+  /**
+   * Formatted UTC timestamp when the user started the application.
+   */
+  app_start_time?: number;
+
+  /**
+   * Application-specific device identifier.
+   */
+  device_app_hash?: string;
+
+  /**
+   * String identifying the kind of build. For example, testflight.
+   */
+  build_type?: string;
+
+  /**
+   * Version-independent application identifier, often a dotted bundle ID.
+   */
+  app_identifier?: string;
+
+  /**
+   * Human readable application name, as it appears on the platform.
+   */
+  app_name?: string;
+
+  /**
+   * Human readable application version, as it appears on the platform.
+   */
+  app_version?: string;
+
+  /**
+   * Internal build identifier, as it appears on the platform.
+   */
+  app_build?: string;
+}

packages/types/src/breadcrumb.ts

@@ -1,14 +1,123 @@
 import { Severity } from './severity';
 
-/** JSDoc */
+/**
+ * Sentry uses breadcrumbs to create a trail of events that happened prior to an issue.
+ * These events are very similar to traditional logs but can record more rich structured data.
+ * @external https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/
+ */
 export interface Breadcrumb {
-  type?: string;
-  level?: Severity;
-  event_id?: string;
+  /**
+   * The type of breadcrumb.
+   * By default, all breadcrumbs are recorded as default,
+   * which makes them appear as a Debug entry,
+   * but Sentry provides other types that influence how the breadcrumbs are rendered.
+   * For more information, see the description of recognized breadcrumb types.
+   */
+  type?: BreadcrumbTypes | string;
+
+  /**
+   * A dotted string indicating what the crumb is or from where it comes.
+   * Typically it is a module name or a descriptive string.
+   */
   category?: string;
+
+  /**
+   * Human readable message for the breadcrumb.
+   * If a message is provided, it is rendered as text with all whitespace preserved.
+   */
   message?: string;
-  data?: { [key: string]: any };
+
+  /**
+   * Arbitrary data associated with this breadcrumb.
+   * Contains a dictionary whose contents depend on the breadcrumb type.
+   * Additional parameters that are unsupported by the type are rendered as a key/value table.
+   */
+  data?: Record<string, unknown>;
+
+  /**
+   * This defines the severity level of the breadcrumb.
+   * Levels are used in the UI to emphasize and deemphasize the crumb.
+   * The default is info.
+   */
+  level?: Severity;
+
+  /**
+   * A timestamp representing when the breadcrumb occurred.
+   * Breadcrumbs are most useful when they include a timestamp,
+   * as it creates a timeline leading up to an event expection/error.
+   */
   timestamp?: number;
+
+  event_id?: string;
+}
+
+/**
+ * @external https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/#breadcrumb-types
+ */
+export enum BreadcrumbTypes {
+  /**
+   * Describes a generic breadcrumb.
+   * This is typically a log message or user-generated breadcrumb.
+   * The data part is entirely undefined and as such, completely rendered as a key/value table.
+   */
+  default = 'default',
+
+  /**
+   * This is typically a log message.
+   *  The data part is entirely undefined and as such, completely rendered as a key/value table.
+   */
+  debug = 'debug',
+
+  /**
+   * An error that occurred before the exception.
+   */
+  error = 'error',
+
+  /**
+   * A navigation event can be a URL change in a web application,
+   * or a UI transition in a mobile or desktop application, etc.
+   * Its data property has the following sub-properties:
+   * - from (Required): A string representing the original application state / location.
+   * - to (Required): A string representing the new application state / location.
+   */
+  navigation = 'navigation',
+
+  /**
+   * This represents an HTTP request transmitted from your application.
+   * This could be an AJAX request from a web application,
+   * or a server-to-server HTTP request to an API service provider, etc.
+   * Its data property has the following sub-properties:
+   * - url (optional): The request URL.
+   * - method (optional): The HTTP request method.
+   * - status_code (optional): The HTTP status code of the response.
+   * - reason (optional): A text that describes the status code.
+   */
+  http = 'http',
+
+  /**
+   * Information that helps identify the root cause of the issue or for whom the error occurred.
+   */
+  info = 'info',
+
+  /**
+   * This represents a query that was made in your application.
+   */
+  query = 'query',
+
+  /**
+   * Describes a tracing event.
+   */
+  transaction = 'transaction',
+
+  /**
+   * A user interaction with your app's UI.
+   */
+  ui = 'ui',
+
+  /**
+   * A user interaction with your app's UI.
+   */
+  user = 'user',
 }
 
 /** JSDoc */

packages/types/src/browsercontext.ts

@@ -0,0 +1,18 @@
+import { Context } from './context';
+
+/**
+ * Browser context carries information about the browser or user agent for web-related errors.
+ * This can either be the browser this event occurred in or the user agent of a web request that triggered the event.
+ * @external https://develop.sentry.dev/sdk/event-payloads/contexts/#browser-context
+ */
+export interface BrowserContext extends Context {
+  /**
+   * Display name of the browser application.
+   */
+  name: string;
+
+  /**
+   * Version string of the browser.
+   */
+  version?: string;
+}

packages/types/src/context.ts

@@ -1,2 +1,9 @@
+/**
+ * The Contexts Interface provides additional context data.
+ * Typically, this is data related to the current user and the environment.
+ * For example, the device or application version.
+ * @external https://develop.sentry.dev/sdk/event-payloads/contexts/
+ */
 export type Context = Record<string, unknown>;
+
 export type Contexts = Record<string, Context>;