@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/gtmCampaigns.d.ts

@@ -0,0 +1,662 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.gtmCampaigns` (GTM Campaigns): 22 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"attach_audience_to_campaign_campaigns__campaign_id__audience_put">;
+ *
+ * Reference with examples: gtmCampaigns.md
+ */
+/* eslint-disable */
+
+/** `g8.api.gtmCampaigns.<member>` -> the operationId it calls. */
+export interface GtmCampaignsMembers {
+  attachAudienceToCampaign: "attach_audience_to_campaign_campaigns__campaign_id__audience_put";
+  createCampaign: "create_campaign_campaigns_post";
+  createCampaignDocument: "create_campaign_document_campaigns__campaign_id__documents_post";
+  createCampaignStep: "create_campaign_step_campaigns__campaign_id__sequence_steps_post";
+  deleteCampaignDocument: "delete_campaign_document_campaigns__campaign_id__documents__document_id__delete";
+  deleteCampaignStep: "delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete";
+  getCampaign: "get_campaign_campaigns__campaign_id__get";
+  getCampaignDocument: "get_campaign_document_campaigns__campaign_id__documents__document_id__get";
+  getCampaignFull: "get_campaign_full_campaigns__campaign_id__full_get";
+  getCampaignMetrics: "get_campaign_metrics_campaigns__campaign_id__metrics_get";
+  getCampaignSequence: "get_campaign_sequence_campaigns__campaign_id__sequence_get";
+  hideCampaignAdImage: "hide_campaign_ad_image_campaigns__campaign_id__ad_images__image_id__hide_post";
+  launchCampaign: "launch_campaign_campaigns__campaign_id__launch_post";
+  listCampaignAdImages: "list_campaign_ad_images_campaigns__campaign_id__ad_images_get";
+  listCampaignDocuments: "list_campaign_documents_campaigns__campaign_id__documents_get";
+  listCampaignIdeas: "list_campaign_ideas_campaigns_ideas_get";
+  listCampaigns: "list_campaigns_campaigns_get";
+  patchCampaignFull: "patch_campaign_full_campaigns__campaign_id__full_patch";
+  updateCampaign: "update_campaign_campaigns__campaign_id__patch";
+  updateCampaignDocument: "update_campaign_document_campaigns__campaign_id__documents__document_id__put";
+  updateCampaignSequence: "update_campaign_sequence_campaigns__campaign_id__sequence_put";
+  updateCampaignStep: "update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put";
+}
+
+/** Input and output of every `g8.api.gtmCampaigns` operation, keyed by operationId. */
+export interface GtmCampaignsOperations {
+  /**
+   * PUT /campaigns/{campaign_id}/audience
+   * Attach Audience To Campaign
+   * tier: external · scope: campaigns:run
+   */
+  attach_audience_to_campaign_campaigns__campaign_id__audience_put: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CampaignAttachAudienceRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /campaigns
+   * Create Campaign
+   * tier: external · scope: campaigns:run
+   */
+  create_campaign_campaigns_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__v1__gtm_campaigns_router__CampaignCreateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /campaigns/{campaign_id}/documents
+   * Create Campaign Document
+   * tier: external · scope: campaigns:run
+   */
+  create_campaign_document_campaigns__campaign_id__documents_post: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CampaignDocumentCreateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /campaigns/{campaign_id}/sequence/steps
+   * Create Campaign Step
+   * tier: external · scope: campaigns:run
+   */
+  create_campaign_step_campaigns__campaign_id__sequence_steps_post: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateStepRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /campaigns/{campaign_id}/documents/{document_id}
+   * Delete Campaign Document
+   * tier: destructive · scope: campaigns:delete
+   */
+  delete_campaign_document_campaigns__campaign_id__documents__document_id__delete: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Document ID */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /campaigns/{campaign_id}/sequence/steps/{step_id}
+   * Delete Campaign Step
+   * tier: destructive · scope: campaigns:delete
+   */
+  delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Step ID */
+      step_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}
+   * Get Campaign
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_campaigns__campaign_id__get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/documents/{document_id}
+   * Get Campaign Document
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_document_campaigns__campaign_id__documents__document_id__get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Document ID */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/full
+   * Get Campaign Full
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_full_campaigns__campaign_id__full_get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/metrics
+   * Get Campaign Metrics
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_metrics_campaigns__campaign_id__metrics_get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    query?: {
+      /** Lookback window in days */
+      days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/sequence
+   * Get Campaign Sequence
+   * tier: read · scope: campaigns:read
+   */
+  get_campaign_sequence_campaigns__campaign_id__sequence_get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /campaigns/{campaign_id}/ad-images/{image_id}/hide
+   * Hide Campaign Ad Image
+   * tier: external · scope: campaigns:run
+   */
+  hide_campaign_ad_image_campaigns__campaign_id__ad_images__image_id__hide_post: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Ad image ID (cb_website_images.id) */
+      image_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /campaigns/{campaign_id}/launch
+   * Launch Campaign
+   * tier: external · scope: campaigns:launch
+   */
+  launch_campaign_campaigns__campaign_id__launch_post: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    query?: {
+      /** Deprecated compatibility parameter. Readiness validation is always enforced; false is rejected before any sequence is created. */
+      validate?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: CampaignLaunchRequest | null;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/ad-images
+   * List Campaign Ad Images
+   * tier: read · scope: campaigns:read
+   */
+  list_campaign_ad_images_campaigns__campaign_id__ad_images_get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/{campaign_id}/documents
+   * List Campaign Documents
+   * tier: read · scope: campaigns:read
+   */
+  list_campaign_documents_campaigns__campaign_id__documents_get: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /campaigns/ideas
+   * List Campaign Ideas
+   * tier: read · scope: campaigns:read
+   */
+  list_campaign_ideas_campaigns_ideas_get: {
+    input: {
+    query?: {
+      /** Items per page */
+      limit?: number;
+      /** Filter favorited ideas */
+      favorited?: boolean | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * GET /campaigns
+   * List Campaigns
+   * tier: read · scope: campaigns:read
+   */
+  list_campaigns_campaigns_get: {
+    input: {
+    query?: {
+      /** Page number */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * PATCH /campaigns/{campaign_id}/full
+   * Patch Campaign Full
+   * tier: external · scope: campaigns:run
+   */
+  patch_campaign_full_campaigns__campaign_id__full_patch: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CampaignFullPatchRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PATCH /campaigns/{campaign_id}
+   * Update Campaign
+   * tier: external · scope: campaigns:run
+   */
+  update_campaign_campaigns__campaign_id__patch: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__v1__gtm_campaigns_router__CampaignUpdateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PUT /campaigns/{campaign_id}/documents/{document_id}
+   * Update Campaign Document
+   * tier: external · scope: campaigns:run
+   */
+  update_campaign_document_campaigns__campaign_id__documents__document_id__put: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Document ID */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CampaignDocumentUpdateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PUT /campaigns/{campaign_id}/sequence
+   * Update Campaign Sequence
+   * tier: external · scope: campaigns:run
+   */
+  update_campaign_sequence_campaigns__campaign_id__sequence_put: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: developer_api__interfaces__v1__gtm_campaigns_router__UpdateSequenceRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PUT /campaigns/{campaign_id}/sequence/steps/{step_id}
+   * Update Campaign Step
+   * tier: external · scope: campaigns:run
+   */
+  update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put: {
+    input: {
+    path: {
+      /** Campaign ID */
+      campaign_id: string;
+      /** Step ID */
+      step_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UpdateStepRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 15 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_dict__ {
+  data: Array<Record<string, unknown>>;
+  pagination?: PaginationMeta | null;
+}
+
+/** Body for PUT /campaigns/{id}/audience — attach (or detach with null) a list. */
+export interface CampaignAttachAudienceRequest {
+  /** List ID to attach as the campaign's audience. Pass null to detach. The list must already exist in this org (matches audiences.id, the canonical lists table — accepts an integer or its string form). */
+  list_id?: string | null;
+}
+
+export interface CampaignDocumentCreateRequest {
+  /** Document content */
+  content?: string;
+  /** Human-readable document name */
+  display_name: string;
+  /** Document type, for example campaign_brief or sequence */
+  file_type: string;
+  /** Optional folder path */
+  folder_path?: string | null;
+  /** Document status — 'draft' (default) or 'completed' */
+  status?: string;
+  /** Optional structured payload (e.g., sequence steps, persona JSON) stored alongside the markdown content at meta_data.structured_data. Mirrors the update path so the MCP create+update flow is symmetric. */
+  structured_data?: Record<string, unknown> | null;
+}
+
+export interface CampaignDocumentUpdateRequest {
+  /** Document content */
+  content?: string;
+  /** Optional document status */
+  status?: string | null;
+  /** Optional structured document data */
+  structured_data?: Record<string, unknown> | null;
+}
+
+/** A single-document patch for `PATCH /campaigns/{id}/full`. */
+export interface CampaignFullPatchDocument {
+  /** Plain string content (replaces existing meta_data.content). */
+  content?: string | null;
+  /** Display name (create only) */
+  display_name?: string | null;
+  /** Required when creating; ignored on update of existing id. */
+  file_type?: string | null;
+  /** Folder path (create only) */
+  folder_path?: string | null;
+  /** Existing document id. When omitted, a new document is created. */
+  id?: string | null;
+  /** Document status */
+  status?: string | null;
+  /** Optional structured data, merged into meta_data.structured_data. */
+  structured_data?: Record<string, unknown> | null;
+}
+
+/**
+ * Deep-update payload for `PATCH /campaigns/{id}/full`.
+ *
+ * Every field is optional. Each non-null section is applied in the same
+ * transaction — campaign fields → audience → documents → sequence — so a
+ * single call can re-shape the whole campaign without ping-pong.
+ */
+export interface CampaignFullPatchRequest {
+  /** If provided (including empty string treated as detach), updates audience_list_id. Use the dedicated PUT /audience endpoint when you only need to attach. */
+  audience_list_id?: string | null;
+  brief?: string | null;
+  category?: string | null;
+  core_concept?: string | null;
+  /** Set true to explicitly DETACH the audience (audience_list_id=NULL). Required because JSON null in audience_list_id is ambiguous (could mean 'no change'). */
+  detach_audience?: boolean;
+  /** Per-document patches. Existing docs are updated in place (id required); new docs are created when id is omitted and file_type+display_name are present. */
+  documents?: Array<CampaignFullPatchDocument> | null;
+  goal?: string | null;
+  /** Existing sequence IDs to bind to this campaign. INSERTs rows with status='linked' into cb_campaign_sequence_links. Skips IDs that are already linked (any status). Use for pre-launch wiring of an existing sequence; launch writes its own 'pushed' audit rows. */
+  linked_sequence_ids?: Array<string> | null;
+  name?: string | null;
+  primary_hook?: string | null;
+  /** If provided, replaces the sequence step ordering (same as PUT /sequence). */
+  sequence_steps?: Array<SequenceStepRef> | null;
+  target_persona?: string | null;
+  /** Sequence IDs to UNLINK from this campaign. DELETEs ONLY rows where status='linked'. Launch-audit rows (status='pushed'/'superseded'/'failed') are never touched — those are an immutable historical record. */
+  unlink_sequence_ids?: Array<string> | null;
+}
+
+/**
+ * Optional body for ``POST /campaigns/{id}/launch`` — all fields optional.
+ *
+ * Callers that POST with no body (or an empty {}) use the first active email
+ * mailbox for the organization. Callers that want explicit control pass
+ * ``sender_mailbox_ids``. Launch fails before sequence creation when no
+ * supported active sender is available.
+ *
+ * The MCP `g8_gtm_launch_campaign` wrapper passes ``sender_mailbox_ids`` when
+ * Daniel's agent already picked a sender; otherwise the auto-pick fallback
+ * keeps the one-shot launch flow working with no extra round-trip.
+ */
+export interface CampaignLaunchRequest {
+  /** Calendar event-type ID (from GET /event-types) to attach as the booking link on the sequence. Stamped onto seqsequences.appointment_id. When omitted no booking link is attached and any sequence step referencing `{{booking_link}}` will render the org-default link (or empty). */
+  appointment_id?: number | null;
+  /**
+   * Deprecated safety escape hatch. Launch now rejects True because a consequential action cannot proceed without an active sender.
+   * @deprecated
+   */
+  disable_auto_pick?: boolean;
+  /** Send-window schedule UUID (from GET /schedules). Stamped onto seqsequences.schedule_id. When omitted the sequencer falls back to its org-default send window. */
+  schedule_id?: string | null;
+  /** Explicit list of mailbox IDs (from GET /mailboxes) to attach as sequence channels before launch. Each ID must reference a connection_status='active', non-archived mailbox in this org. When omitted, the bridge auto-picks the first active email mailbox (ORDER BY id ASC). If no supported sender is available, launch fails before sequence creation. */
+  sender_mailbox_ids?: Array<number> | null;
+  /** Voice-service agent identifier (from GET /agents) used for email / social steps. Stamped onto seqsequences.textual_agent_name. Pass the same value as `voice_agent_name` to use one agent across all channels (the common case — the unified Agent row already bundles persona + voice + phone + the attached appointment event). */
+  textual_agent_name?: string | null;
+  /** Voice-service agent identifier (from GET /agents) used for phone / SMS steps. Stamped onto seqsequences.voice_agent_name. When you want a single agent for all channels, set both this and `textual_agent_name` to the same value. */
+  voice_agent_name?: string | null;
+}
+
+export interface CreateStepRequest {
+  angle_id?: string | null;
+  channel: string;
+  condition?: string | null;
+  constraints?: Record<string, unknown>;
+  cta_type?: string;
+  day: number;
+  mode: string;
+  name: string;
+  personalization_level?: string;
+  platform?: string | null;
+  stop_on_reply?: boolean;
+}
+
+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;
+}
+
+export interface SequenceStepRef {
+  condition?: string | null;
+  day: number;
+  step_id: string;
+  stop_on_reply?: boolean;
+}
+
+export interface UpdateStepRequest {
+  angle_id?: string | null;
+  channel?: string | null;
+  condition?: string | null;
+  constraints?: Record<string, unknown> | null;
+  cta_type?: string | null;
+  day?: number | null;
+  do_not_send_rules?: Array<string> | null;
+  mode?: string | null;
+  name?: string | null;
+  personalization_level?: string | null;
+  platform?: string | null;
+  stop_on_reply?: boolean | null;
+}
+
+export interface developer_api__interfaces__v1__gtm_campaigns_router__CampaignCreateRequest {
+  /** If provided, attaches this list ID to cb_campaigns.audience_list_id at create time. */
+  audience_list_id?: string | null;
+  /** When True, dispatches the Celery campaign-content generator asynchronously after creation: the paired cb_campaign_ideas row is inserted (so the FE workbench sees the campaign), cb_campaign_metadata is created, the campaign starts in status='copy_in_progress', and flips to 'active' once docs are ready (~60-90s). Default is False to preserve byte-for-byte backwards compatibility with the original bare-bones draft behavior — the MCP tool wrapper sets True explicitly to opt into Studio parity. */
+  auto_generate_documents?: boolean;
+  /** Campaign brief */
+  brief?: string | null;
+  /** Campaign category */
+  category?: string;
+  /** Core concept */
+  core_concept?: string | null;
+  /** Execution destinations: sequencer, dialer, or content_only. */
+  execution_targets?: Array<string> | null;
+  /** Campaign goal */
+  goal?: string | null;
+  /** Campaign name */
+  name: string;
+  /** Primary hook text */
+  primary_hook?: string | null;
+  /** Additional hook variations to seed the campaign idea with. */
+  secondary_hooks?: Array<string> | null;
+  /** Channels the campaign will use, e.g. ['email'], ['email','linkedin']. Drives which copy documents the auto-generator creates. Defaults to ['email']. */
+  target_channels?: Array<string> | null;
+  /** Target persona */
+  target_persona?: string | null;
+}
+
+export interface developer_api__interfaces__v1__gtm_campaigns_router__CampaignUpdateRequest {
+  /** Campaign brief */
+  brief?: string | null;
+  /** Campaign category */
+  category?: string | null;
+  /** Core concept */
+  core_concept?: string | null;
+  /** Campaign goal */
+  goal?: string | null;
+  /** Campaign name */
+  name?: string | null;
+  /** Primary hook text */
+  primary_hook?: string | null;
+  /** Target persona */
+  target_persona?: string | null;
+}
+
+export interface developer_api__interfaces__v1__gtm_campaigns_router__UpdateSequenceRequest {
+  steps: Array<SequenceStepRef>;
+}