@graph8/sdk 0.251.0 → 0.260.0

package/dist/types/webhooks.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Known graph8 webhook event types.
+ *
+ * Source of truth is the backend ``WEBHOOK_EVENTS`` catalog
+ * (campaign_builder/services/webhook_service.py). Keep in sync when the backend
+ * adds events. ``WebhookEvent`` also accepts any string so a newly-added
+ * backend event never breaks a client that hasn't upgraded.
+ */
+export declare const KNOWN_WEBHOOK_EVENTS: readonly ["campaign.created", "campaign.updated", "campaign.deleted", "campaign.launched", "campaign.paused", "campaign.completed", "campaign.status_changed", "campaign.content_ready", "document.generated", "document.failed", "intelligence.completed", "intelligence.failed", "company.enriched", "company_intelligence.completed", "audience.ready", "audience.failed", "sequence.draft_created", "sequence.started", "sequence.paused", "sequence.completed", "engagement.email_sent", "engagement.email_replied", "engagement.email_bounced", "engagement.email_skipped", "engagement.call_dispatched", "engagement.call_connected", "engagement.call_graded", "engagement.sms_sent", "engagement.sms_replied", "engagement.whatsapp_sent", "engagement.linkedin_connection_sent", "engagement.linkedin_message_sent", "engagement.linkedin_inmail_sent", "engagement.linkedin_reply_received", "engagement.linkedin_connection_accepted", "meeting.booked", "meeting.cancelled", "meeting.rescheduled", "deal.won", "crm.record.created", "crm.record.updated", "crm.record.archived", "crm.record.restored", "sequence.contact_enrolled", "sequence.contact_removed", "sequence.step_completed", "sequence.step_failed", "engagement.contact_unsubscribed", "engagement.sms_delivered", "engagement.sms_failed", "engagement.whatsapp_delivered", "engagement.whatsapp_failed", "engagement.call_started", "engagement.call_completed", "engagement.call_disposition_set", "engagement.voicemail_detected", "engagement.voicemail_left", "engagement.email_clicked", "engagement.link_clicked", "engagement.call_recording_ready", "meeting.no_show", "voice_ai.call_started", "voice_ai.call_completed", "voice_ai.voicemail_left", "deal.created", "deal.updated", "deal.stage_changed", "deal.deleted", "quote.created", "quote.updated", "quote.sent", "quote.resent", "quote.resend_failed", "quote.link_generated", "quote.viewed", "quote.accepted", "quote.declined", "quote.expired", "quote.voided", "quote.superseded", "quote.archived", "quote.unarchived", "quote.payment_received", "quote.payment_failed", "quote.subscription_canceled", "quote.provisioned", "form.submitted", "visitor.identified", "intent.signal", "task.created", "task.updated", "task.completed", "task.deleted", "enrichment.job_completed", "enrichment.job_failed", "workflow.execution_completed", "workflow.execution_failed"];
+export type WebhookEvent = (typeof KNOWN_WEBHOOK_EVENTS)[number] | (string & {});
+/** The decoded body graph8 delivers to a webhook endpoint. */
+export interface WebhookEventPayload {
+    event: WebhookEvent;
+    timestamp: string;
+    data: Record<string, unknown>;
+    org_id: string;
+    /** Stable event ID for consumer deduplication; delivery ID is in X-Studio-Delivery-Id. */
+    id?: string;
+}
+export interface ConstructEventOptions {
+    /**
+     * Reject events whose ``X-Studio-Timestamp`` is older (or newer) than this
+     * many seconds — replay protection. Disabled when 0/undefined.
+     */
+    toleranceSeconds?: number;
+}
+/** Thrown by {@link constructEvent} when a webhook cannot be verified. */
+export declare class WebhookSignatureError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify the HMAC-SHA256 signature of an incoming graph8 webhook and return the
+ * parsed event. Server-side only (needs the per-endpoint signing secret).
+ *
+ * Mirrors the backend signing scheme exactly: the signature is
+ * ``HMAC_SHA256(secret, `${timestamp}.${rawBody}`)`` hex-encoded, delivered in
+ * the ``X-Studio-Signature`` header alongside the unix ``X-Studio-Timestamp``.
+ *
+ * @param payload    The RAW request body string (verify before JSON.parse — re-serializing changes bytes).
+ * @param signature  The ``X-Studio-Signature`` header (an optional ``sha256=`` prefix is tolerated).
+ * @param timestamp  The ``X-Studio-Timestamp`` header (unix seconds).
+ * @param secret     The endpoint's signing secret.
+ * @throws {WebhookSignatureError} on a missing/invalid signature, stale timestamp, or bad JSON.
+ *
+ * @example
+ *   app.post("/webhooks/graph8", (req, res) => {
+ *     const event = g8.webhooks.constructEvent(
+ *       req.rawBody,
+ *       req.header("X-Studio-Signature"),
+ *       req.header("X-Studio-Timestamp"),
+ *       process.env.G8_WEBHOOK_SECRET,
+ *       { toleranceSeconds: 300 },
+ *     );
+ *     if (event.event === "meeting.booked") { ... }
+ *     res.sendStatus(200);
+ *   });
+ */
+export declare function constructEvent(payload: string, signature: string, timestamp: string | number, secret: string, opts?: ConstructEventOptions): WebhookEventPayload;
+/**
+ * Webhooks client (server-side). graph8 webhooks are PUSH — graph8 POSTs to your
+ * endpoint; you verify each delivery with {@link constructEvent}. (The previous
+ * polling implementation hit a feed endpoint that never existed and is removed.)
+ */
+export declare const createWebhooksClient: (_apiKey: string, apiUrl?: string) => {
+    /** Base URL the webhook subscription API lives under. */
+    baseUrl: string;
+    /** Known event types (for autocomplete / validation). */
+    knownEvents: readonly ["campaign.created", "campaign.updated", "campaign.deleted", "campaign.launched", "campaign.paused", "campaign.completed", "campaign.status_changed", "campaign.content_ready", "document.generated", "document.failed", "intelligence.completed", "intelligence.failed", "company.enriched", "company_intelligence.completed", "audience.ready", "audience.failed", "sequence.draft_created", "sequence.started", "sequence.paused", "sequence.completed", "engagement.email_sent", "engagement.email_replied", "engagement.email_bounced", "engagement.email_skipped", "engagement.call_dispatched", "engagement.call_connected", "engagement.call_graded", "engagement.sms_sent", "engagement.sms_replied", "engagement.whatsapp_sent", "engagement.linkedin_connection_sent", "engagement.linkedin_message_sent", "engagement.linkedin_inmail_sent", "engagement.linkedin_reply_received", "engagement.linkedin_connection_accepted", "meeting.booked", "meeting.cancelled", "meeting.rescheduled", "deal.won", "crm.record.created", "crm.record.updated", "crm.record.archived", "crm.record.restored", "sequence.contact_enrolled", "sequence.contact_removed", "sequence.step_completed", "sequence.step_failed", "engagement.contact_unsubscribed", "engagement.sms_delivered", "engagement.sms_failed", "engagement.whatsapp_delivered", "engagement.whatsapp_failed", "engagement.call_started", "engagement.call_completed", "engagement.call_disposition_set", "engagement.voicemail_detected", "engagement.voicemail_left", "engagement.email_clicked", "engagement.link_clicked", "engagement.call_recording_ready", "meeting.no_show", "voice_ai.call_started", "voice_ai.call_completed", "voice_ai.voicemail_left", "deal.created", "deal.updated", "deal.stage_changed", "deal.deleted", "quote.created", "quote.updated", "quote.sent", "quote.resent", "quote.resend_failed", "quote.link_generated", "quote.viewed", "quote.accepted", "quote.declined", "quote.expired", "quote.voided", "quote.superseded", "quote.archived", "quote.unarchived", "quote.payment_received", "quote.payment_failed", "quote.subscription_canceled", "quote.provisioned", "form.submitted", "visitor.identified", "intent.signal", "task.created", "task.updated", "task.completed", "task.deleted", "enrichment.job_completed", "enrichment.job_failed", "workflow.execution_completed", "workflow.execution_failed"];
+    /** Verify an incoming webhook's HMAC signature and return the parsed event. */
+    constructEvent(payload: string, signature: string, timestamp: string | number, secret: string, opts?: ConstructEventOptions): WebhookEventPayload;
+};

package/dist/types/workflows.d.ts

@@ -0,0 +1,229 @@
+export interface WorkflowNode {
+    id: string;
+    type: string;
+    config: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Mapping from this node's output to the next node's input. */
+    input_mappings?: Record<string, string>;
+}
+export interface WorkflowConnection {
+    from_node_id: string;
+    to_node_id: string;
+    condition?: string | null;
+}
+export interface WorkflowConfig {
+    nodes: WorkflowNode[];
+    connections: WorkflowConnection[];
+    trigger?: Record<string, unknown> | null;
+}
+export interface Workflow {
+    id: string;
+    name: string;
+    description: string | null;
+    config: WorkflowConfig;
+    trigger_config: Record<string, unknown> | null;
+    is_active: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface WorkflowCreateParams {
+    name: string;
+    description?: string;
+    config?: WorkflowConfig;
+    trigger_config?: Record<string, unknown>;
+}
+export interface WorkflowUpdateParams {
+    name?: string;
+    description?: string;
+    config?: WorkflowConfig;
+    trigger_config?: Record<string, unknown>;
+    is_active?: boolean;
+}
+export interface WorkflowExecution {
+    id: string;
+    workflow_id: string;
+    status: "pending" | "running" | "paused" | "completed" | "failed" | "stopped";
+    trigger_payload: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    error: string | null;
+    started_at: string | null;
+    ended_at: string | null;
+}
+export interface NodeTypeSchema {
+    type: string;
+    label: string;
+    description: string;
+    config_schema: Record<string, unknown>;
+    output_schema: Record<string, unknown>;
+}
+export interface WorkflowListParams {
+    page?: number;
+    limit?: number;
+    is_active?: boolean;
+    search?: string;
+}
+/**
+ * Workflows API - automation workflows with nodes, connections, and execution lifecycle.
+ * Requires API key (server-side). On the hardened HTTP core: throws a typed
+ * `G8Error` on failure and retries transient errors.
+ *
+ * The graph8 workflow surface treats the whole workflow definition as a single
+ * record updated via `update()` — there are no per-node CRUD endpoints. To edit
+ * nodes or connections, fetch the workflow, mutate `config.nodes` / `config.connections`,
+ * and PUT it back.
+ *
+ * Backed by:
+ *   GET    /api/v1/workflows
+ *   GET    /api/v1/workflows/{id}
+ *   POST   /api/v1/workflows
+ *   PUT    /api/v1/workflows/{id}
+ *   DELETE /api/v1/workflows/{id}
+ *   POST   /api/v1/workflows/validate
+ *   POST   /api/v1/workflows/{id}/execute
+ *   GET    /api/v1/workflows/executions/{exec_id}
+ *   POST   /api/v1/workflows/executions/{exec_id}/pause
+ *   POST   /api/v1/workflows/executions/{exec_id}/resume
+ *   POST   /api/v1/workflows/executions/{exec_id}/stop
+ *   GET    /api/v1/workflows/{id}/trigger-status
+ *   POST   /api/v1/workflows/{id}/trigger-reset
+ *   GET    /api/v1/workflows/node-types/schema
+ *   GET    /api/v1/workflows/integrations/slack/users|channels
+ *   GET    /api/v1/workflows/integrations/roam/users|groups
+ *   GET    /api/v1/workflows/mcp-servers
+ *   GET    /api/v1/workflows/dispositions
+ *   GET    /api/v1/workflows/forms/{form_id}/fields
+ */
+export declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
+    /** List workflows org-wide. */
+    list(params?: WorkflowListParams): Promise<{
+        data: Workflow[];
+    }>;
+    /** Get full workflow definition (nodes, connections, trigger, execution state). */
+    get(workflowId: string): Promise<Workflow>;
+    /** Create a new workflow. */
+    create(params: WorkflowCreateParams): Promise<Workflow>;
+    /**
+     * Update a workflow. Pass the full `config` (nodes + connections) to edit
+     * the graph — node-level CRUD is performed client-side by mutating the
+     * config and submitting the updated record.
+     */
+    update(workflowId: string, fields: WorkflowUpdateParams): Promise<Workflow>;
+    /** Delete a workflow. */
+    delete(workflowId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+    /** Validate a workflow definition (orphans, dangling connections, required fields). */
+    validate(workflow: {
+        config: WorkflowConfig;
+        trigger_config?: Record<string, unknown>;
+    }): Promise<{
+        data: {
+            valid: boolean;
+            errors: Array<{
+                node_id?: string;
+                field?: string;
+                message: string;
+            }>;
+        };
+    }>;
+    /** Execute a workflow immediately with a trigger payload. */
+    execute(workflowId: string, triggerPayload?: Record<string, unknown>): Promise<WorkflowExecution>;
+    /** Get the status + outputs of a single execution. */
+    getExecution(executionId: string): Promise<WorkflowExecution>;
+    /** Pause a running execution. */
+    pauseExecution(executionId: string): Promise<{
+        data: {
+            paused: boolean;
+        };
+    }>;
+    /** Resume a paused execution. */
+    resumeExecution(executionId: string): Promise<{
+        data: {
+            resumed: boolean;
+        };
+    }>;
+    /** Stop an execution. */
+    stopExecution(executionId: string): Promise<{
+        data: {
+            stopped: boolean;
+        };
+    }>;
+    /** Get the trigger status (e.g. schedule / webhook wiring) for a workflow. */
+    getTriggerStatus(workflowId: string): Promise<{
+        data: {
+            status: string;
+            details: Record<string, unknown>;
+        };
+    }>;
+    /** Reset a workflow's trigger cursor / state. */
+    resetTrigger(workflowId: string): Promise<{
+        data: {
+            reset: boolean;
+        };
+    }>;
+    /** Catalog of available workflow node types with config + output schemas. */
+    nodeTypes(params?: {
+        type?: string;
+    }): Promise<{
+        data: NodeTypeSchema[];
+    }>;
+    /** Slack users available to workflow nodes. */
+    listSlackUsers(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+            email: string | null;
+        }>;
+    }>;
+    /** Slack channels available to workflow nodes. */
+    listSlackChannels(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+            is_private: boolean;
+        }>;
+    }>;
+    /** Roam users available to workflow nodes. */
+    listRoamUsers(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+            email: string | null;
+        }>;
+    }>;
+    /** Roam groups available to workflow nodes. */
+    listRoamGroups(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+    /** MCP servers available to workflow nodes. */
+    listMcpServers(): Promise<{
+        data: Array<{
+            id: string;
+            name: string;
+            url: string;
+        }>;
+    }>;
+    /** Disposition options available to workflow nodes. */
+    listDispositions(): Promise<{
+        data: Array<{
+            id: string;
+            label: string;
+        }>;
+    }>;
+    /** Form field definitions for a given form (used by form-trigger nodes). */
+    listFormFields(formId: string): Promise<{
+        data: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+        }>;
+    }>;
+};