@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/revenue.d.ts

@@ -0,0 +1,402 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.revenue` (Revenue): 14 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"cancel_stage_doc_backfill_job_revenue_backfills__job_id__cancel_post">;
+ *
+ * Reference with examples: revenue.md
+ */
+/* eslint-disable */
+
+/** `g8.api.revenue.<member>` -> the operationId it calls. */
+export interface RevenueMembers {
+  cancelStageDocBackfillJob: "cancel_stage_doc_backfill_job_revenue_backfills__job_id__cancel_post";
+  estimateAllStageDocBackfills: "estimate_all_stage_doc_backfills_revenue_backfills_estimate_post";
+  estimateStageDocBackfill: "estimate_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_estimate_post";
+  getEventCatalog: "get_event_catalog_revenue_lifecycle_event_catalog_get";
+  getStageDocBackfillJob: "get_stage_doc_backfill_job_revenue_backfills__job_id__get";
+  getStageDocCatalog: "get_stage_doc_catalog_revenue_stage_docs_catalog_get";
+  getStageDocDefaults: "get_stage_doc_defaults_revenue_stage_docs_defaults_get";
+  getStageDocSlot: "get_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__get";
+  patchStageDocSlot: "patch_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__patch";
+  resetStageDocSlot: "reset_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__reset_post";
+  seedLifecycleDefaults: "seed_lifecycle_defaults_revenue_lifecycle_seed_defaults_post";
+  startStageDocBackfill: "start_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_post";
+  syncLifecycleLists: "sync_lifecycle_lists_revenue_lifecycle_sync_lists_post";
+  updateLifecycles: "update_lifecycles_revenue_lifecycle_put";
+}
+
+/** Input and output of every `g8.api.revenue` operation, keyed by operationId. */
+export interface RevenueOperations {
+  /**
+   * POST /revenue/backfills/{job_id}/cancel
+   * Cancel Stage Doc Backfill Job
+   * tier: destructive · scope: deals:delete
+   */
+  cancel_stage_doc_backfill_job_revenue_backfills__job_id__cancel_post: {
+    input: {
+    path: {
+      /** Backfill job id (UUID). */
+      job_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/backfills/estimate
+   * Estimate All Stage Doc Backfills
+   * tier: read · scope: deals:read
+   */
+  estimate_all_stage_doc_backfills_revenue_backfills_estimate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill/estimate
+   * Estimate Stage Doc Backfill
+   * tier: read · scope: deals:read
+   */
+  estimate_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_estimate_post: {
+    input: {
+    path: {
+      /** Lifecycle stage id (UUID). */
+      lifecycle_entry_id: string;
+      /** Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. */
+      entity: "company" | "contact";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /revenue/lifecycle/event-catalog
+   * Get Event Catalog
+   * tier: read · scope: deals:read
+   */
+  get_event_catalog_revenue_lifecycle_event_catalog_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportListPayload_;
+  };
+  /**
+   * GET /revenue/backfills/{job_id}
+   * Get Stage Doc Backfill Job
+   * tier: read · scope: deals:read
+   */
+  get_stage_doc_backfill_job_revenue_backfills__job_id__get: {
+    input: {
+    path: {
+      /** Backfill job id (UUID). */
+      job_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /revenue/stage-docs/catalog
+   * Get Stage Doc Catalog
+   * tier: read · scope: deals:read
+   */
+  get_stage_doc_catalog_revenue_stage_docs_catalog_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportListPayload_;
+  };
+  /**
+   * GET /revenue/stage-docs/defaults
+   * Get Stage Doc Defaults
+   * tier: read · scope: deals:read
+   */
+  get_stage_doc_defaults_revenue_stage_docs_defaults_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /revenue/stage-docs/{lifecycle_entry_id}/{entity}
+   * Get Stage Doc Slot
+   * tier: read · scope: deals:read
+   */
+  get_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__get: {
+    input: {
+    path: {
+      /** Lifecycle stage id (UUID). */
+      lifecycle_entry_id: string;
+      /** Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. */
+      entity: "company" | "contact";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * PATCH /revenue/stage-docs/{lifecycle_entry_id}/{entity}
+   * Patch Stage Doc Slot
+   * tier: write · scope: deals:write
+   */
+  patch_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__patch: {
+    input: {
+    path: {
+      /** Lifecycle stage id (UUID). */
+      lifecycle_entry_id: string;
+      /** Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. */
+      entity: "company" | "contact";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: StageDocSlotPatchRequest;
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/stage-docs/{lifecycle_entry_id}/{entity}/reset
+   * Reset Stage Doc Slot
+   * tier: destructive · scope: deals:delete
+   */
+  reset_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__reset_post: {
+    input: {
+    path: {
+      /** Lifecycle stage id (UUID). */
+      lifecycle_entry_id: string;
+      /** Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. */
+      entity: "company" | "contact";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/lifecycle/seed-defaults
+   * Seed Lifecycle Defaults
+   * tier: destructive · scope: deals:delete
+   */
+  seed_lifecycle_defaults_revenue_lifecycle_seed_defaults_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill
+   * Start Stage Doc Backfill
+   * tier: billable · scope: knowledge:run
+   */
+  start_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_post: {
+    input: {
+    path: {
+      /** Lifecycle stage id (UUID). */
+      lifecycle_entry_id: string;
+      /** Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. */
+      entity: "company" | "contact";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: StageBackfillRequest;
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * POST /revenue/lifecycle/sync-lists
+   * Sync Lifecycle Lists
+   * tier: write · scope: deals:write
+   */
+  sync_lifecycle_lists_revenue_lifecycle_sync_lists_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * PUT /revenue/lifecycle
+   * Update Lifecycles
+   * tier: write · scope: deals:write
+   */
+  update_lifecycles_revenue_lifecycle_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateLifecyclesRequest;
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+}
+
+// 12 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ReportListPayload_ {
+  data: ReportListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ReportPayload_ {
+  data: ReportPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * One Revenue lifecycle stage.
+ *
+ * `id` is REQUIRED and may be the empty string: the app assigns a fresh UUID
+ * to any entry that arrives without one, which is how a new stage is created.
+ * Mirrored as required-but-emptyable rather than optional so the field cannot
+ * be omitted by accident on an entry that was meant to be an UPDATE - a
+ * missing id there does not fail, it silently creates a duplicate stage and
+ * orphans the original's documents.
+ */
+export interface LifecycleEntryRequest {
+  auto_hide_if_empty?: boolean;
+  churn_reason_categories?: Array<string> | null;
+  custom_status_match?: Array<string>;
+  description?: string | null;
+  event_tracking?: LifecycleEventTrackingRequest | null;
+  hidden?: boolean;
+  icon?: string;
+  id: string;
+  is_system_seed?: boolean;
+  name: string;
+  slug: string;
+  sort_order?: number;
+  status_match?: Array<string>;
+  subscription_filter?: Array<string> | null;
+}
+
+/** One tracked platform event configured against a lifecycle stage. */
+export interface LifecycleEventConfigRequest {
+  /** activation | usage | expansion | risk | aha_moment */
+  bucket: string;
+  description?: string | null;
+  display_name: string;
+  event_name: string;
+  path_to_paid_step?: number | null;
+  weight?: number | null;
+}
+
+export interface LifecycleEventTrackingRequest {
+  enabled?: boolean;
+  events?: Array<LifecycleEventConfigRequest>;
+}
+
+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;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * An OPEN envelope for a report that answers with a bare LIST.
+ *
+ * A bare list is reachable as `items`; a named list (`{"counts": {...}}`)
+ * keeps its own key AND gains `items`, so a caller can read either shape
+ * without branching.
+ */
+export interface ReportListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An OPEN envelope around one report's answer.
+ *
+ * The app wraps every one of these reports in `{success, data, meta}`, where
+ * `meta` carries the cache state, the window and - on the agency reports -
+ * `failed_org_ids`, the orgs that contributed NOTHING to the totals above.
+ * That field is the difference between "this client sent no email" and "we
+ * could not query this client", so it is forwarded rather than flattened
+ * away.
+ *
+ * Open on purpose: `data` is `dict | list` in the app and its contents grow
+ * with the product. A closed model would turn every new metric into a
+ * silently dropped one.
+ */
+export type ReportPayload = Record<string, unknown>;
+
+/**
+ * Start a stage-document backfill. SPENDS CREDITS.
+ *
+ * `max_credits` is a REAL ceiling, not a hint: the worker stops the job the
+ * moment `credits_used >= credits_cap`. Call the estimate first and set it
+ * from the figure you get back.
+ */
+export interface StageBackfillRequest {
+  /** Must be true. The app refuses the call with 400 otherwise - a deliberate second hand on a job that spends credits. */
+  confirm: boolean;
+  /** Hard credit ceiling for this job. The worker stops when spend reaches it. REQUIRED - there is no default, because a default would be a number nobody chose. */
+  max_credits: number;
+}
+
+/**
+ * Merge-update for ONE (stage, entity) document slot.
+ *
+ * Every field is optional and only the ones you SEND are applied - but note
+ * the app drops `None` values from the patch rather than writing them, so a
+ * field cannot be cleared by sending null. Send the value you want instead.
+ */
+export interface StageDocSlotPatchRequest {
+  auto_generate?: boolean | null;
+  credit_cap?: number | null;
+  docs?: Array<StageDocSpecRequest> | null;
+  on_demand?: Array<string> | null;
+  reuse_if_fresh_days?: number | null;
+  top_n_contacts?: number | null;
+}
+
+export interface StageDocSpecRequest {
+  mandatory?: boolean;
+  schedule?: Record<string, unknown> | null;
+  tier?: string;
+  trigger?: "instant" | "scheduled";
+  type: string;
+}
+
+/**
+ * REPLACES the whole `entries` array. A stage left out is DELETED.
+ *
+ * This is a PUT in the app and a PUT here for that reason: it is not a
+ * merge. Read `GET /lifecycle-stages` first and send the full list back with
+ * your change applied.
+ */
+export interface UpdateLifecyclesRequest {
+  entries: Array<LifecycleEntryRequest>;
+}