@graph8/sdk 0.308.1 → 0.357.0

package/docs/api/reports.d.ts

@@ -0,0 +1,476 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.reports` (Reports): 7 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"archive_object_report_api_reports__report_id__delete">;
+ *
+ * Reference with examples: reports.md
+ */
+/* eslint-disable */
+
+/** `g8.api.reports.<member>` -> the operationId it calls. */
+export interface ReportsMembers {
+  archiveObjectReportApi: "archive_object_report_api_reports__report_id__delete";
+  createObjectReportApi: "create_object_report_api_reports_post";
+  executeObjectReportApi: "execute_object_report_api_reports__report_id__execute_post";
+  getObjectReportApi: "get_object_report_api_reports__report_id__get";
+  listObjectReportsApi: "list_object_reports_api_reports_get";
+  previewObjectReportApi: "preview_object_report_api_reports_preview_post";
+  updateObjectReportApi: "update_object_report_api_reports__report_id__patch";
+}
+
+/** Input and output of every `g8.api.reports` operation, keyed by operationId. */
+export interface ReportsOperations {
+  /**
+   * DELETE /reports/{report_id}
+   * Archive Object Report Api
+   * tier: destructive · scope: objects:delete
+   */
+  archive_object_report_api_reports__report_id__delete: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_NoneType_;
+  };
+  /**
+   * POST /reports
+   * Create Object Report Api
+   * tier: write · scope: objects:write
+   */
+  create_object_report_api_reports_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReportCreate;
+  };
+    output: ApiResponse_ReportDefinitionResponse_;
+  };
+  /**
+   * POST /reports/{report_id}/execute
+   * Execute Object Report Api
+   * tier: write · scope: objects:read
+   */
+  execute_object_report_api_reports__report_id__execute_post: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReportRun;
+  };
+    output: ReportRunApiResponse;
+  };
+  /**
+   * GET /reports/{report_id}
+   * Get Object Report Api
+   * tier: read · scope: objects:read
+   */
+  get_object_report_api_reports__report_id__get: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportDefinitionResponse_;
+  };
+  /**
+   * GET /reports
+   * List Object Reports Api
+   * tier: read · scope: objects:read
+   */
+  list_object_reports_api_reports_get: {
+    input: {
+    query?: {
+      object_slug?: string | null;
+      owner?: string | null;
+      visibility?: string | null;
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportListResponse_;
+  };
+  /**
+   * POST /reports/preview
+   * Preview Object Report Api
+   * tier: write · scope: objects:read
+   */
+  preview_object_report_api_reports_preview_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReportPreview;
+  };
+    output: ApiResponse_ReportResult_;
+  };
+  /**
+   * PATCH /reports/{report_id}
+   * Update Object Report Api
+   * tier: write · scope: objects:write
+   */
+  update_object_report_api_reports__report_id__patch: {
+    input: {
+    path: {
+      report_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ReportUpdate;
+  };
+    output: ApiResponse_ReportDefinitionResponse_;
+  };
+}
+
+// 37 schemas referenced above (the same as G8Contract.<Name>).
+
+/** Every record behind the report (the totals row). */
+export interface AllTarget {
+  kind?: "all";
+}
+
+export interface ApiResponse_NoneType_ {
+  data: null;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ReportDefinitionResponse_ {
+  data: ReportDefinitionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ReportListResponse_ {
+  data: ReportListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ReportResult_ {
+  data: ReportResult;
+  pagination?: PaginationMeta | null;
+}
+
+export interface AsOf {
+  date: string;
+  instant: string;
+  timezone: string;
+}
+
+/**
+ * What the chart folds into "Other": every group beyond ``chart_limit``. Only additive measures (count, sum,
+ * related_count) are filled in; an average, minimum or maximum cannot be folded and is None.
+ */
+export interface ChartOther {
+  group_count: number;
+  measures: Record<string, number | null>;
+  record_count: number;
+}
+
+export interface DrilldownColumn {
+  label: string;
+  slug: string;
+  value_type: string;
+}
+
+export interface DrilldownRecord {
+  display?: string | null;
+  extra?: Record<string, unknown>;
+  id: string;
+  values?: Record<string, unknown>;
+}
+
+/** Open the records behind one number: ``target`` is a result row's ``drilldown``, echoed back unchanged. */
+export interface DrilldownRequest {
+  after_record_id?: string | null;
+  limit?: number;
+  target: GroupTarget | StageTarget | SnapshotTarget | AllTarget;
+}
+
+export interface DrilldownResult {
+  columns?: Array<DrilldownColumn>;
+  kind?: "drilldown";
+  measures?: Record<string, number | null>;
+  next_after_record_id?: string | null;
+  records?: Array<DrilldownRecord>;
+  restricted?: Array<RestrictedComponent>;
+  status?: "ok" | "restricted";
+  total?: number;
+}
+
+export interface GapNote {
+  component: string;
+  kind?: "no_history";
+  records: number;
+}
+
+/**
+ * One row of a table, bar or line report: the group values in dimension order. ``gaps[i]`` is
+ * ``"no_history"`` when dimension *i* is the history-gap group of an as-of report. A numeric value a JSON number
+ * cannot carry exactly (past 15 significant digits) is its exact decimal text here; echo the target unchanged.
+ */
+export interface GroupTarget {
+  gaps?: Array<"no_history" | null>;
+  kind?: "group";
+  values?: Array<unknown>;
+}
+
+export interface GroupValue {
+  gap?: "no_history" | null;
+  id: string;
+  value?: unknown;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
+}
+
+/**
+ * What a report computes. ``timezone`` (an IANA name) fixes how dates are bucketed and what "end of day" means;
+ * when absent the organization's time zone applies (never the server's).
+ */
+export interface ReportConfig {
+  filters?: Array<ReportFilter>;
+  group_by?: Array<ReportGroupBy>;
+  measures?: Array<ReportMeasure>;
+  range?: ReportRange | null;
+  stage?: ReportStage | null;
+  timezone?: string | null;
+}
+
+export interface ReportCreate {
+  chart_type: "table" | "bar" | "line" | "funnel" | "stage_over_time" | "time_in_stage";
+  config: ReportConfig;
+  description?: string | null;
+  object_slug: string;
+  title: string;
+  visibility?: "private" | "org";
+}
+
+export interface ReportDefinitionResponse {
+  can_delete: boolean;
+  can_edit: boolean;
+  chart_type: "table" | "bar" | "line" | "funnel" | "stage_over_time" | "time_in_stage";
+  config: Record<string, unknown>;
+  created_at: string;
+  description?: string | null;
+  id: string;
+  is_owner: boolean;
+  owner: ReportOwner;
+  restricted?: Array<RestrictedComponent>;
+  restricted_count?: number;
+  revision: number;
+  source: ReportSource;
+  title: string;
+  updated_at: string;
+  visibility: "private" | "org";
+}
+
+/**
+ * One filter on a field of the source, or (with ``relationship_slug``) on a field of the contact, company or deal
+ * the source points at: the record passes when a linked record it may see matches. ``in`` is "is any of" and takes a
+ * list of values.
+ */
+export interface ReportFilter {
+  attribute_slug: string;
+  operator: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "is_null" | "is_not_null" | "in";
+  relationship_slug?: string | null;
+  value?: unknown;
+}
+
+/**
+ * One group-by. ``attribute``: a field of the source (a date or timestamp field needs a ``grain``);
+ * ``related_attribute``: a field of the ONE record a single-valued relationship points at; ``created_at``: the
+ * record's creation time, bucketed by ``grain``.
+ */
+export interface ReportGroupBy {
+  attribute_slug?: string | null;
+  grain?: ("day" | "week" | "month" | "quarter" | "year") | null;
+  kind?: "attribute" | "related_attribute" | "created_at";
+  relationship_slug?: string | null;
+}
+
+export interface ReportListResponse {
+  can_share: boolean;
+  reports: Array<ReportDefinitionResponse>;
+  total: number;
+}
+
+/**
+ * One measure. ``count`` counts each record once (COUNT DISTINCT record id); ``sum`` / ``avg`` / ``min`` / ``max``
+ * read a numeric field's value; ``related_count`` counts the live records a relationship links each record to.
+ */
+export interface ReportMeasure {
+  attribute_slug?: string | null;
+  kind: "count" | "sum" | "avg" | "min" | "max" | "related_count";
+  label?: string | null;
+  relationship_slug?: string | null;
+}
+
+export interface ReportOwner {
+  id?: string | null;
+  is_you?: boolean;
+  name?: string | null;
+}
+
+/** Run an unsaved report with the caller's own access (the builder's live preview). No drilldown. */
+export interface ReportPreview {
+  as_of?: string | null;
+  chart_type: "table" | "bar" | "line" | "funnel" | "stage_over_time" | "time_in_stage";
+  config: ReportConfig;
+  object_slug: string;
+}
+
+/**
+ * The calendar range a stage-over-time report snapshots, one column per ``grain`` period end (in the report's
+ * time zone).
+ */
+export interface ReportRange {
+  from: string;
+  grain?: "day" | "week" | "month" | "quarter" | "year";
+  to: string;
+}
+
+export interface ReportResult {
+  as_of?: AsOf | null;
+  chart_limit?: number;
+  chart_other?: ChartOther | null;
+  chart_truncated?: boolean;
+  chart_type: "table" | "bar" | "line" | "funnel" | "stage_over_time" | "time_in_stage";
+  columns?: Array<ResultColumn>;
+  disclosures?: Array<string>;
+  gaps?: Array<GapNote>;
+  history_supported?: boolean;
+  kind?: "result";
+  restricted?: Array<RestrictedComponent>;
+  row_limit?: number;
+  rows?: Array<ResultRow>;
+  source: ReportSource;
+  status?: "ok" | "restricted";
+  timezone: string;
+  total_base_records?: number;
+  total_groups?: number;
+  totals?: ResultTotals | null;
+  truncated?: boolean;
+}
+
+/** Run a saved report. ``as_of`` is a calendar date in the report's time zone (end of that day); absent = now. */
+export interface ReportRun {
+  as_of?: string | null;
+  drilldown?: DrilldownRequest | null;
+}
+
+/**
+ * A report run: its result, or a page of the records behind a number when ``drilldown`` was asked (``data.kind``).
+ * Named so the published schema is ``ReportRunApiResponse`` rather than a generated name of the union.
+ */
+export interface ReportRunApiResponse {
+  data: ReportResult | DrilldownResult;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ReportSource {
+  is_archived?: boolean;
+  kind: "object" | "process_list";
+  plural_noun: string;
+  singular_noun: string;
+  slug: string;
+}
+
+/** The stage field and the ORDERED stages a funnel, stage-over-time or time-in-stage report walks. */
+export interface ReportStage {
+  attribute_slug: string;
+  order: Array<string>;
+}
+
+export interface ReportUpdate {
+  chart_type?: ("table" | "bar" | "line" | "funnel" | "stage_over_time" | "time_in_stage") | null;
+  config?: ReportConfig | null;
+  description?: string | null;
+  expected_revision?: number | null;
+  title?: string | null;
+  visibility?: ("private" | "org") | null;
+}
+
+/**
+ * A part of a report the viewer may not see. Hidden means ABSENT: it carries no title, no object name, no type and
+ * no reason, only its position id (``m0`` the first measure, ``g0`` the first group-by, ``f0`` the first filter,
+ * ``stage`` the stage field), so a client can lock that slot in place.
+ */
+export interface RestrictedComponent {
+  id: string;
+  restricted?: true;
+}
+
+export interface ResultColumn {
+  grain?: ("day" | "week" | "month" | "quarter" | "year") | null;
+  id: string;
+  kind: "group_by" | "measure" | "stage" | "gap";
+  label?: string | null;
+  restricted?: boolean;
+  value_type?: string | null;
+}
+
+export interface ResultRow {
+  drilldown: GroupTarget | StageTarget | SnapshotTarget | AllTarget;
+  group?: Array<GroupValue>;
+  key: string;
+  measures?: Record<string, number | null>;
+  partial?: boolean;
+  record_count?: number;
+  unstaged?: Record<string, number>;
+}
+
+export interface ResultTotals {
+  measures?: Record<string, number | null>;
+  record_count: number;
+}
+
+/**
+ * One cell of a stage-over-time report, on the last day of the period that ends on ``bucket_end``: every record
+ * live then (``all``), the records in ``stage`` (``stage``), those with no stage (``unstaged``) or those with no
+ * recorded stage history (``no_history``).
+ */
+export interface SnapshotTarget {
+  bucket_end: string;
+  cell?: "all" | "stage" | "unstaged" | "no_history";
+  kind?: "snapshot";
+  stage?: string | null;
+}
+
+/** One stage of a funnel or time-in-stage report. */
+export interface StageTarget {
+  kind?: "stage";
+  stage: string;
+}