@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/sequenceLifecycle.d.ts

@@ -0,0 +1,439 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.sequenceLifecycle` (Sequence Lifecycle): 8 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_sequence_sequences_post">;
+ *
+ * Reference with examples: sequenceLifecycle.md
+ */
+/* eslint-disable */
+
+/** `g8.api.sequenceLifecycle.<member>` -> the operationId it calls. */
+export interface SequenceLifecycleMembers {
+  createSequence: "create_sequence_sequences_post";
+  deleteSequence: "delete_sequence_sequences__sequence_id__delete";
+  getSequenceAnalytics: "get_sequence_analytics_sequences__sequence_id__analytics_get";
+  listSequenceSteps: "list_sequence_steps_sequences__sequence_id__steps_get";
+  previewSequence: "preview_sequence_sequences__sequence_id__preview_get";
+  removeLinkedinChannel: "remove_linkedin_channel_sequences__sequence_id__channels_linkedin_delete";
+  updateSequence: "update_sequence_sequences__sequence_id__patch";
+  updateSequenceStep: "update_sequence_step_sequences__sequence_id__steps__step_id__patch";
+}
+
+/** Input and output of every `g8.api.sequenceLifecycle` operation, keyed by operationId. */
+export interface SequenceLifecycleOperations {
+  /**
+   * POST /sequences
+   * Create Sequence
+   * tier: external · scope: sequences:run
+   */
+  create_sequence_sequences_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SequenceCreateRequest;
+  };
+    output: ApiResponse_SequenceCreateResponse_;
+  };
+  /**
+   * DELETE /sequences/{sequence_id}
+   * Delete Sequence
+   * tier: destructive · scope: sequences:delete
+   */
+  delete_sequence_sequences__sequence_id__delete: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SequenceActionResponse_;
+  };
+  /**
+   * GET /sequences/{sequence_id}/analytics
+   * Get Sequence Analytics
+   * tier: read · scope: sequences:read
+   */
+  get_sequence_analytics_sequences__sequence_id__analytics_get: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SequenceAnalyticsResponse_;
+  };
+  /**
+   * GET /sequences/{sequence_id}/steps
+   * List Sequence Steps
+   * tier: read · scope: sequences:read
+   */
+  list_sequence_steps_sequences__sequence_id__steps_get: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SequenceStepsResponse_;
+  };
+  /**
+   * GET /sequences/{sequence_id}/preview
+   * Preview Sequence
+   * tier: read · scope: sequences:read
+   */
+  preview_sequence_sequences__sequence_id__preview_get: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SequencePreviewResponse_;
+  };
+  /**
+   * DELETE /sequences/{sequence_id}/channels/linkedin
+   * Remove Linkedin Channel
+   * tier: destructive · scope: sequences:delete
+   */
+  remove_linkedin_channel_sequences__sequence_id__channels_linkedin_delete: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    query?: {
+      /** Preview exactly what would be removed without writing anything. */
+      dry_run?: boolean;
+      /** Required to operate on a LIVE or WAITING sequence. The sequence is paused afterwards either way so the result can be reviewed before it resumes sending. */
+      force?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_LinkedInChannelRemovalResponse_;
+  };
+  /**
+   * PATCH /sequences/{sequence_id}
+   * Update Sequence
+   * tier: external · scope: sequences:run
+   */
+  update_sequence_sequences__sequence_id__patch: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SequenceUpdateRequest;
+  };
+    output: ApiResponse_SequenceActionResponse_;
+  };
+  /**
+   * PATCH /sequences/{sequence_id}/steps/{step_id}
+   * Update Sequence Step
+   * tier: external · scope: sequences:run
+   */
+  update_sequence_step_sequences__sequence_id__steps__step_id__patch: {
+    input: {
+    path: {
+      /** Sequence ID */
+      sequence_id: string;
+      /** Step ID */
+      step_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: StepUpdateRequest;
+  };
+    output: ApiResponse_SequenceActionResponse_;
+  };
+}
+
+// 22 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_LinkedInChannelRemovalResponse_ {
+  data: LinkedInChannelRemovalResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequenceActionResponse_ {
+  data: SequenceActionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequenceAnalyticsResponse_ {
+  data: SequenceAnalyticsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequenceCreateResponse_ {
+  data: SequenceCreateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequencePreviewResponse_ {
+  data: SequencePreviewResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SequenceStepsResponse_ {
+  data: SequenceStepsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ChannelConfig {
+  /** Extra channel metadata */
+  channel_data?: Record<string, unknown> | null;
+  /** Channel resource ID (mailbox ID, phone ID, etc.) */
+  channel_id: number;
+  /** Channel type. One of: SMTP, GMAIL, INBOXKIT, PHONE, LINKEDIN, SMS, WHATSAPP. Case-insensitive. */
+  channel_type: string;
+  /** Channel value (email address, phone number, etc.) */
+  channel_value: string;
+}
+
+/**
+ * Result of removing a sequence's LinkedIn steps and channel binding together.
+ *
+ * Nothing bound is a SUCCESS with zero counts, never a 404 — that is what makes
+ * the operation safe to call across a batch of sequences without inspecting each
+ * one first, and it doubles as the cleanup path for a sequence already stuck
+ * with orphaned LinkedIn steps.
+ */
+export interface LinkedInChannelRemovalResponse {
+  /** True when a LIVE/WAITING sequence was paused as part of this operation */
+  auto_paused: boolean;
+  /** Persisted channel_type that was unbound, e.g. LINKEDIN_NETRION */
+  channel_type_removed?: string | null;
+  /** Number of LinkedIn channel bindings removed */
+  channels_removed: number;
+  /** True when nothing was written */
+  dry_run: boolean;
+  /** LinkedIn provider detected: NETRION, HEYREACH, or null when none was bound */
+  provider?: string | null;
+  /** Live channel bindings left afterwards */
+  remaining_channel_count: number;
+  /** Steps left on the sequence afterwards */
+  remaining_step_count: number;
+  /** The steps that were (or would be) removed */
+  removed_steps?: Array<RemovedStepSummary>;
+  /** Sequence that was operated on */
+  sequence_id: string;
+  /** True when the sequence has no steps left */
+  sequence_now_empty: boolean;
+  /** Sequence status after the operation */
+  status_after: string;
+  /** Sequence status before the operation */
+  status_before: string;
+  /** Number of LinkedIn steps deleted */
+  steps_removed: number;
+  /** Advisory notes the caller should surface to the user */
+  warnings?: Array<string>;
+}
+
+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 PreviewChannelItem {
+  channel_id?: number | null;
+  channel_type?: string | null;
+  channel_value?: string | null;
+  id: string;
+}
+
+export interface PreviewStepItem {
+  id: string;
+  input_type: string;
+  /** Spintax-resolved view of this step's copy. Populated for template steps that carry subject/body. Null for ON_DEMAND steps, whose copy is written by the AI at send time rather than stored here. */
+  rendered?: RenderedStepContent | null;
+  step_data?: Record<string, unknown> | null;
+  step_order: number;
+  step_type: string;
+  time_interval?: number | null;
+}
+
+/** One step removed by the LinkedIn-removal operation. */
+export interface RemovedStepSummary {
+  /** Step ID that was removed */
+  id: string;
+  /** Position the step held before removal */
+  step_order: number;
+  /** Persisted step type, e.g. NETRION or HEYREACH */
+  step_type: string;
+}
+
+/**
+ * What a step's copy actually looks like once spintax is resolved.
+ *
+ * Exists because ``step_data`` is the stored TEMPLATE, not the delivered email.
+ * A caller reading raw ``{{a|b|c}}`` back out of a field called "preview" has no
+ * way to tell working spintax from broken spintax, which is precisely how a
+ * working feature got reported as broken (see the PR that added this).
+ */
+export interface RenderedStepContent {
+  /** Body with spintax resolved to one variant */
+  body: string;
+  /** Findings from the same content-syntax validator that blocks launch, so a caller sees them here instead of discovering them as a 400 on run (or worse, as missing text in a delivered email). Each entry carries code, severity, message, field and snippet. An error-severity entry will block POST /sequences/{id}/run. */
+  content_issues?: Array<Record<string, unknown>>;
+  /** Count of top-level spintax blocks across subject + body. 0 means this step contains no spintax at all, which distinguishes 'nothing to vary' from 'spintax failed to resolve'. */
+  spintax_blocks: number;
+  /** Subject with spintax resolved to one variant */
+  subject: string;
+  /** Distinct emails this step can produce. Always >= 1; a value of exactly 1 means the copy is too templated to vary, which is a legitimate outcome and not an error. */
+  total_combinations: number;
+  /** False for this endpoint. Spintax is resolved but {{variables}} are left visible on purpose, because a preview has no contact and resolving against an empty contact would delete the token and show a hole in the copy. Variables fill in at send time. */
+  variables_resolved?: boolean;
+  /** Up to 3 distinct body renderings under different selection seeds. This is the proof that spintax works: if these differ, per-contact variation is functioning. Fewer than 3 entries means the copy cannot produce more. */
+  variants?: Array<string>;
+  /** True when the rendered copy above is what a recipient actually gets. False means content_issues contains errors that make the delivered email differ from this preview, because malformed tokens are silently DELETED at send rather than raising. Do not launch on a false. */
+  will_send_as_shown?: boolean;
+}
+
+export interface SequenceActionResponse {
+  contacts_affected?: number;
+  sequence_id: string;
+  status: string;
+}
+
+export interface SequenceAnalyticsResponse {
+  contact_distribution?: Record<string, unknown>;
+  engagement?: Record<string, unknown>;
+  overview?: Record<string, unknown>;
+  performance?: Record<string, unknown>;
+  sender_distribution?: Array<Record<string, unknown>>;
+  step_breakdown?: Array<Record<string, unknown>>;
+  step_creation_methods?: Array<Record<string, unknown>>;
+  timeline?: Array<Record<string, unknown>>;
+}
+
+export interface SequenceCreateRequest {
+  /** Contact list to associate */
+  associated_list_id?: number | null;
+  /** AI Studio campaign to link */
+  campaign_id?: string | null;
+  /** Channels to attach */
+  channels?: Array<ChannelConfig> | null;
+  /** Sequence description */
+  description?: string | null;
+  /** Stop contacting on reply */
+  finish_on_reply?: boolean;
+  /** Sequence name */
+  name: string;
+  /** Mailbox ID to pin for a nurture sequence. Required when sequence_kind='nurture'; all email channels must use this mailbox. Ignored for cold_outbound sequences. */
+  pinned_mailbox_id?: number | null;
+  /** Send follow-ups in same email thread */
+  send_in_same_thread?: boolean;
+  /** Sequence kind: 'cold_outbound' (default) or 'nurture'. Immutable after creation. 'nurture' requires pinned_mailbox_id and is gated by the ENABLE_NURTURE feature flag. */
+  sequence_kind?: string | null;
+  /** Sequence steps to create */
+  steps?: Array<StepConfig> | null;
+  /** Owner email address. Omit it to make the person who minted this API key the owner (org keys that record no creator must still send it). */
+  user_email?: string | null;
+  /** Keep sequence waiting for new contacts */
+  wait_for_new_contacts?: boolean;
+}
+
+export interface SequenceCreateResponse {
+  created_at?: string | null;
+  id: string;
+  name: string;
+  status: string;
+}
+
+export interface SequencePreviewResponse {
+  channels?: Array<PreviewChannelItem>;
+  description?: string | null;
+  id: string;
+  name?: string | null;
+  status?: string | null;
+  steps?: Array<PreviewStepItem>;
+}
+
+/**
+ * Response for ``GET /sequences/{id}/steps``.
+ *
+ * This route exists because callers reach for it first and used to get a bare
+ * 404, which sent them to ``/preview`` and its unrendered copy instead.
+ */
+export interface SequenceStepsResponse {
+  sequence_id: string;
+  steps?: Array<PreviewStepItem>;
+}
+
+export interface SequenceUpdateRequest {
+  /** Calendar event-type ID (from GET /event-types). Stamped onto seqsequences.appointment_id. */
+  appointment_id?: number | null;
+  /** Sequence description */
+  description?: string | null;
+  /** Finish on reply */
+  finish_on_reply?: boolean | null;
+  /** Whether sequence is shared */
+  is_shared?: boolean | null;
+  /** Sequence name */
+  name?: string | null;
+  /** Send-window schedule UUID (from GET /schedules). Stamped onto seqsequences.schedule_id. */
+  schedule_id?: string | null;
+  /** Send in same thread */
+  send_in_same_thread?: boolean | null;
+  /** Voice-service agent identifier (from GET /voice/dialer/agents) for email / social steps. Stamped onto seqsequences.textual_agent_name. The same value as voice_agent_name is the common case (one agent across channels). */
+  textual_agent_name?: string | null;
+  /** Voice-service agent identifier (from GET /voice/dialer/agents) for phone / SMS steps. Stamped onto seqsequences.voice_agent_name. */
+  voice_agent_name?: string | null;
+  /** Wait for new contacts */
+  wait_for_new_contacts?: boolean | null;
+}
+
+export interface StepConfig {
+  /** Input type. One of: ON_DEMAND, MANUAL_TEMPLATE, AI_GENERATED_TEMPLATE. Case-insensitive aliases accepted (e.g. 'template' -> MANUAL_TEMPLATE, 'ai' -> AI_GENERATED_TEMPLATE). */
+  input_type?: string;
+  /** Step template/content data (subject, body, instructions, etc.) */
+  step_data?: Record<string, unknown> | null;
+  /** Order of the step in the sequence (1-based) */
+  step_order: number;
+  /** Step type. One of: EMAIL, PHONE, SMS, WHATSAPP, HEYREACH, MANUAL_DIALER. Note: LinkedIn outreach uses HEYREACH (not LINKEDIN). Case-insensitive aliases accepted. */
+  step_type: string;
+  /** Delay in seconds after the previous step */
+  time_interval?: number;
+}
+
+export interface StepUpdateRequest {
+  /** Input type. One of: ON_DEMAND, MANUAL_TEMPLATE, AI_GENERATED_TEMPLATE. Case-insensitive. */
+  input_type?: string | null;
+  /** Step template/content data */
+  step_data?: Record<string, unknown> | null;
+  /** Step type. One of: EMAIL, PHONE, SMS, WHATSAPP, HEYREACH, MANUAL_DIALER. Case-insensitive. */
+  step_type?: string | null;
+  /** Delay in seconds after the previous step */
+  time_interval?: number | null;
+}