@oxygen-agent/cli 1.146.1 → 1.160.18

package/node_modules/@oxygen/shared/dist/sequences.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Multichannel sequence DSL — the shared contract validated identically by CLI,
+ * MCP, API, and web. A sequence is an ordered list of steps applied to each
+ * enrolled lead, spanning LinkedIn (executed natively by the sequencer dispatch
+ * engine) and email (native send through a mailbox, or delegated to a bound
+ * Instantly campaign). Three control kinds make it cross-channel:
+ *
+ * - wait_for_signal — gate until a provider signal fires (LinkedIn connection
+ *   accepted, email opened/replied, ...) or timeout_days elapse; generalizes
+ *   the LinkedIn-only wait_for_connection gate.
+ * - branch — evaluate a condition over the signals an enrollment has
+ *   accumulated and jump to a target step (then) or fall through (else).
+ * - stop — explicit terminal step, the only way to give a branch's two arms
+ *   genuinely distinct endings.
+ *
+ * A LinkedIn-only sequence (channels = ['linkedin'], no email steps) is exactly
+ * the behavior of the original LinkedIn sequencer, so the same engine and tables
+ * back both. This module is the single home for the schema; the legacy
+ * `linkedin-sequences.ts` validator remains for back-compat reads of stored
+ * LinkedIn-only definitions.
+ *
+ * Email steps: email_send/email_reply send natively through one of the
+ * sequence's mailboxes (Gmail API / Microsoft Graph) — Oxygen owns the send.
+ * email_enroll/move/stop delegate to a bound Instantly campaign (legacy, removed
+ * once native send fully replaces them); Instantly owns send cadence, warmup,
+ * and inbox rotation while Oxygen owns the cross-channel timeline + reply
+ * suppression.
+ */
+export declare const SEQUENCE_CHANNELS: readonly ["linkedin", "email"];
+export type SequenceChannel = (typeof SEQUENCE_CHANNELS)[number];
+/**
+ * Signals an enrollment accumulates from provider webhooks. wait_for_signal gates
+ * and signal-branch conditions read these. linkedin_connected also advances the
+ * legacy wait_for_connection gate. (The lead's current connection *degree* is NOT
+ * a signal — it's resolved on demand by the dispatcher via a connection branch,
+ * `condition: "already_connected"`.)
+ */
+export declare const SEQUENCE_SIGNALS: readonly ["linkedin_connected", "linkedin_replied", "email_sent", "email_opened", "email_clicked", "email_replied", "email_bounced"];
+export type SequenceSignal = (typeof SEQUENCE_SIGNALS)[number];
+/**
+ * row_values keys an enrollment's email may live under, in send-precedence order.
+ * The dispatcher picks the FIRST present key as the recipient address; the
+ * enrollment-lookup queries OR across all of them (order-independent there).
+ * Single source of truth so the send path and the lookup path can't drift.
+ */
+export declare const SEQUENCE_EMAIL_COLUMN_KEYS: readonly ["email", "email_address", "work_email", "primary_email", "Email"];
+export declare const SEQUENCE_STEP_KINDS: readonly ["visit_profile", "invite", "wait_for_connection", "message", "inmail", "email_send", "email_reply", "email_enroll", "email_move", "email_stop", "wait", "wait_for_signal", "branch", "stop"];
+export type SequenceStepKind = (typeof SEQUENCE_STEP_KINDS)[number];
+export type SequenceLinkedInVisitProfileStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "visit_profile";
+};
+export type SequenceLinkedInInviteStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "invite";
+    /** Optional connection-request note. Supports {{column}} interpolation. ~300 char max on LinkedIn. */
+    note_template?: string;
+};
+export type SequenceLinkedInWaitForConnectionStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "wait_for_connection";
+    timeout_days: number;
+    on_timeout: "stop" | "continue";
+};
+export type SequenceLinkedInMessageStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "message";
+    template: string;
+};
+export type SequenceLinkedInInMailStep = {
+    id: string;
+    channel: "linkedin";
+    kind: "inmail";
+    subject_template: string;
+    template: string;
+};
+export type SequenceEmailEnrollStep = {
+    id: string;
+    channel: "email";
+    kind: "email_enroll";
+    /** Optional Instantly subsequence to enroll into (a specific angle); defaults to the main sequence. */
+    subsequence_id?: string;
+};
+export type SequenceEmailMoveStep = {
+    id: string;
+    channel: "email";
+    kind: "email_move";
+    /** Instantly subsequence to move the lead into (switch angle). Required. */
+    subsequence_id: string;
+};
+export type SequenceEmailStopStep = {
+    id: string;
+    channel: "email";
+    kind: "email_stop";
+};
+/**
+ * Native per-step email send through one of the sequence's mailboxes (Gmail API
+ * / Microsoft Graph). Oxygen owns the send; no Instantly campaign.
+ */
+export type SequenceEmailSendStep = {
+    id: string;
+    channel: "email";
+    kind: "email_send";
+    /** Subject line. Supports {{column}} interpolation. */
+    subject_template: string;
+    /** Body. Supports {{column}} interpolation. */
+    body_template: string;
+};
+/** Threaded follow-up in the same email thread as the lead's prior email_send. */
+export type SequenceEmailReplyStep = {
+    id: string;
+    channel: "email";
+    kind: "email_reply";
+    /** Reply body. Supports {{column}} interpolation. */
+    body_template: string;
+};
+export type SequenceWaitStep = {
+    id: string;
+    kind: "wait";
+    days?: number;
+    hours?: number;
+};
+export type SequenceWaitForSignalStep = {
+    id: string;
+    kind: "wait_for_signal";
+    signal: SequenceSignal;
+    /** Days to wait for the signal before acting on on_timeout. */
+    timeout_days: number;
+    /** "stop" ends the sequence on timeout; "continue" advances to the next step. Defaults to "stop". */
+    on_timeout: "stop" | "continue";
+};
+/**
+ * Conditions a connection branch routes on. Both need live LinkedIn access, so
+ * the dispatcher (not the planner) resolves them over time:
+ * - connection_accepted: wait until the invite is accepted (or timeout_days) then
+ *   route accepted → then_id, timeout → else_id.
+ * - already_connected: resolve the lead's current 1st-degree state at entry and
+ *   route connected → then_id, not → else_id (no waiting).
+ */
+export declare const SEQUENCE_CONNECTION_BRANCH_CONDITIONS: readonly ["connection_accepted", "already_connected"];
+export type SequenceConnectionBranchCondition = (typeof SEQUENCE_CONNECTION_BRANCH_CONDITIONS)[number];
+/**
+ * A branch has two flavors, discriminated by the runtime type of `condition`:
+ * - SequenceConnectionBranchStep (string condition) — a LinkedIn connection
+ *   branch resolved by the dispatcher over time, routed by then_id/else_id.
+ * - SequenceSignalBranchStep (object condition) — a synchronous expression over
+ *   the signals the enrollment has accumulated, routed by then/else.
+ * Keeping the string form (rather than mapping it to a signal) is load-bearing:
+ * the dispatcher's degree-probe / accept-wait machinery only runs for the string
+ * form, and stored LinkedIn-only definitions round-trip through this validator
+ * unchanged.
+ */
+export type SequenceConnectionBranchStep = {
+    id: string;
+    kind: "branch";
+    condition: SequenceConnectionBranchCondition;
+    /** connection_accepted only: days to wait for acceptance (default 14). */
+    timeout_days?: number;
+    /** Step id when TRUE (accepted / already connected). Omitted = end this path. */
+    then_id?: string;
+    /** Step id when FALSE / timeout. Omitted = stop this path. */
+    else_id?: string;
+};
+export type SequenceSignalBranchStep = {
+    id: string;
+    kind: "branch";
+    condition: SequenceSignalCondition;
+    /** Step id to jump to when the condition is true. null/omitted = fall through to the next step. */
+    then: string | null;
+    /** Step id to jump to when the condition is false. null/omitted = fall through to the next step. */
+    else: string | null;
+};
+export type SequenceBranchStep = SequenceConnectionBranchStep | SequenceSignalBranchStep;
+/**
+ * Explicit terminal step. Ends the enrollment here regardless of any steps that
+ * follow in the array — the only way to give a branch's two arms genuinely
+ * distinct endings (e.g. a "warm" message that stops, vs an invite→wait→"cold"
+ * message that stops), instead of forcing both arms to fall through into the
+ * same trailing step.
+ */
+export type SequenceStopStep = {
+    id: string;
+    kind: "stop";
+};
+/**
+ * A boolean expression over the signals an enrollment has accumulated. A leaf
+ * tests whether a signal is present (default) or absent (present:false).
+ */
+export type SequenceSignalCondition = {
+    signal: SequenceSignal;
+    present?: boolean;
+} | {
+    all: SequenceSignalCondition[];
+} | {
+    any: SequenceSignalCondition[];
+} | {
+    not: SequenceSignalCondition;
+};
+export type SequenceStep = SequenceLinkedInVisitProfileStep | SequenceLinkedInInviteStep | SequenceLinkedInWaitForConnectionStep | SequenceLinkedInMessageStep | SequenceLinkedInInMailStep | SequenceEmailSendStep | SequenceEmailReplyStep | SequenceEmailEnrollStep | SequenceEmailMoveStep | SequenceEmailStopStep | SequenceWaitStep | SequenceWaitForSignalStep | SequenceBranchStep | SequenceStopStep;
+export type SequenceDefinition = {
+    steps: SequenceStep[];
+};
+/** Which channel a step executes on, or null for channel-agnostic control steps. */
+export declare function sequenceStepChannel(step: SequenceStep): SequenceChannel | null;
+/** Distinct channels a sequence touches (drives the sequence's channels[] tag). */
+export declare function sequenceChannels(definition: SequenceDefinition): SequenceChannel[];
+export type SequenceLintIssue = {
+    path: string;
+    message: string;
+};
+export type ValidateSequenceOptions = {
+    /** When provided, every channel-bearing step must use one of these channels. */
+    allowedChannels?: SequenceChannel[];
+};
+/**
+ * Validate + normalize a raw sequence definition. Assigns stable ids to steps
+ * that omit one (s{index}), verifies branch/gate targets resolve, and enforces
+ * per-step shapes + channel restrictions. Returns the normalized definition or
+ * throws OxygenError("invalid_sequence") with per-step issues. Pure.
+ */
+export declare function validateSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceDefinition;
+/** Non-throwing variant for lint surfaces. */
+export declare function lintSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceLintIssue[];
+/** Total delay in milliseconds a wait step introduces. */
+export declare function sequenceWaitStepDelayMs(step: SequenceWaitStep): number;
+/** Render a {{column}} template against a row's values (reuses the LinkedIn impl). */
+export declare function renderSequenceTemplate(template: string, values: Record<string, unknown>): string;
+/** Column keys referenced by {{...}} placeholders across every step's copy. */
+export declare function sequenceTemplateVariables(definition: SequenceDefinition): string[];
+/**
+ * Evaluate a condition against the set of signals an enrollment has fired.
+ * Used by the dispatch planner for branch steps. Pure.
+ */
+export declare function evaluateSequenceCondition(condition: SequenceSignalCondition, firedSignals: Iterable<string>): boolean;