@graph8/sdk 0.303.0 → 0.357.0

package/blocks/sequencer/lib/sequencer-utils.ts

@@ -0,0 +1,168 @@
+"use client";
+
+/**
+ * Types and pure helpers for the sequencer components: the step kinds, how a draft step becomes an API step,
+ * what makes a step invalid BEFORE it is sent (the API accepts some broken steps and only fails at send
+ * time), and sequence status helpers.
+ */
+
+export type StepKind = "email" | "linkedin" | "call" | "task";
+
+/** UI step kind -> the API `step_type`. `linkedin` is HeyReach; `task` is a manual dialer task. */
+export const STEP_TYPE: Record<StepKind, string> = { email: "EMAIL", linkedin: "HEYREACH", call: "PHONE", task: "MANUAL_DIALER" };
+export const KIND_LABEL: Record<StepKind, string> = { email: "Email", linkedin: "LinkedIn", call: "Call", task: "Call task" };
+export const KINDS = Object.keys(STEP_TYPE) as StepKind[];
+
+export const LINKEDIN_ACTIONS = ["CONNECTION_REQUEST", "MESSAGE", "INMAIL", "FOLLOW", "VIEW_PROFILE", "LIKE_POST"] as const;
+export type LinkedinAction = (typeof LINKEDIN_ACTIONS)[number];
+export type InputType = "MANUAL_TEMPLATE" | "AI_GENERATED_TEMPLATE" | "ON_DEMAND";
+
+export interface DraftStep {
+  /** Local key for React lists. */
+  key: string;
+  /** The API step id once the step is saved. */
+  id?: string;
+  kind: StepKind;
+  input_type: InputType;
+  /** Wait before this step, in days (the API wants seconds). */
+  wait_days: number;
+  step_data: Record<string, unknown>;
+  /** True once changed since it was loaded or saved. */
+  dirty?: boolean;
+}
+
+export interface SequenceRow {
+  id: string;
+  name?: string | null;
+  status?: string | null;
+  step_count?: number | null;
+  contact_count?: number | null;
+  sequence_kind?: string | null;
+  associated_list_id?: number | null;
+  updated_at?: string | null;
+}
+
+export interface ApiStep {
+  id?: string;
+  step_order: number;
+  step_type: string;
+  input_type?: string;
+  time_interval?: number | null;
+  step_data?: Record<string, unknown> | null;
+}
+
+let counter = 0;
+export const newKey = (): string => `step-${Date.now().toString(36)}-${counter++}`;
+
+export function newStep(kind: StepKind): DraftStep {
+  const data: Record<string, unknown> =
+    kind === "email"
+      ? { subject: "", body: "" }
+      : kind === "linkedin"
+        ? { linkedin_action_type: "CONNECTION_REQUEST", linkedin_connection_message: "" }
+        : { dial_dnc: false, phone_options: ["mobile", "direct"] };
+  return { key: newKey(), kind, input_type: "MANUAL_TEMPLATE", wait_days: 2, step_data: data };
+}
+
+export function kindOf(stepType: string | undefined): StepKind {
+  const t = (stepType ?? "").toUpperCase();
+  if (t === "HEYREACH" || t === "NETRION" || t === "UNIPILE" || t === "ARLINK" || t.includes("LINKEDIN")) return "linkedin";
+  if (t === "PHONE") return "call";
+  if (t === "MANUAL_DIALER") return "task";
+  return "email";
+}
+
+export function fromApiStep(s: ApiStep): DraftStep {
+  return {
+    key: s.id ?? newKey(),
+    id: s.id,
+    kind: kindOf(s.step_type),
+    input_type: (s.input_type as InputType) ?? "MANUAL_TEMPLATE",
+    wait_days: (s.time_interval ?? 0) / 86400,
+    step_data: { ...(s.step_data ?? {}) },
+  };
+}
+
+/** The request shape for create and add-steps. `order` is 1-based. */
+export function toApiStep(step: DraftStep, order: number) {
+  return {
+    step_order: order,
+    step_type: STEP_TYPE[step.kind],
+    input_type: step.input_type,
+    time_interval: Math.max(0, Math.round(step.wait_days * 86400)),
+    step_data: step.step_data,
+  };
+}
+
+const text = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+/** Problems that would make the API accept the step but fail or send nothing later. Empty means fine. */
+export function stepIssues(step: DraftStep): string[] {
+  const d = step.step_data;
+  if (step.kind === "email") {
+    if (step.input_type === "ON_DEMAND") return text(d.instructions) ? [] : ["Tell the AI what to write in the instructions."];
+    if (step.input_type === "AI_GENERATED_TEMPLATE") return text(d.instructions) ? [] : ["Add instructions for the AI template."];
+    return [!text(d.subject) && "Add a subject.", !text(d.body) && "Add a body."].filter(Boolean) as string[];
+  }
+  if (step.kind === "linkedin") {
+    const action = text(d.linkedin_action_type);
+    if (!action) return ["Choose a LinkedIn action."];
+    const need: Partial<Record<string, string>> = {
+      CONNECTION_REQUEST: "linkedin_connection_message",
+      MESSAGE: "linkedin_message_text",
+      INMAIL: "linkedin_inmail_body",
+    };
+    const key = need[action];
+    return key && !text(d[key]) ? ["Add the message for this LinkedIn action."] : [];
+  }
+  return [];
+}
+
+/** A `{{token}}` that is opened but not closed, or the reverse: the sender silently deletes these. */
+export function hasBrokenTokens(value: string): boolean {
+  return (value.match(/\{\{/g) ?? []).length !== (value.match(/\}\}/g) ?? []).length;
+}
+
+export function statusGroup(status: string | null | undefined): "draft" | "live" | "paused" | "ended" | "busy" {
+  const s = (status ?? "").toLowerCase();
+  if (["live", "waiting", "running", "active"].includes(s)) return "live";
+  if (s === "paused") return "paused";
+  if (["terminated", "completed", "archived", "finished"].includes(s)) return "ended";
+  if (["scheduling", "pausing", "resuming", "terminating"].includes(s)) return "busy";
+  return "draft";
+}
+
+export const STATUS_CLASS: Record<ReturnType<typeof statusGroup>, string> = {
+  draft: "bg-gray-100 text-gray-700",
+  live: "bg-green-100 text-green-800",
+  paused: "bg-amber-100 text-amber-800",
+  ended: "bg-slate-100 text-slate-600",
+  busy: "bg-blue-100 text-blue-800",
+};
+
+export function listOf<T>(envelope: unknown): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  if (Array.isArray(data)) return data as T[];
+  const obj = data as Record<string, unknown> | null | undefined;
+  for (const key of ["items", "steps", "rows"]) if (Array.isArray(obj?.[key])) return obj![key] as T[];
+  return [];
+}
+
+export function objectOf(envelope: unknown): Record<string, unknown> {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+}
+
+/** Map a mailbox's provider to the sequence channel type the API takes. */
+export function channelTypeFor(provider: string | null | undefined): "GMAIL" | "INBOXKIT" | "SMTP" {
+  const p = (provider ?? "").toLowerCase();
+  if (p.includes("gmail") || p.includes("google")) return "GMAIL";
+  if (p.includes("inboxkit") || p.includes("managed")) return "INBOXKIT";
+  return "SMTP";
+}
+
+export function newIdempotencyKey(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `g8-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}

package/blocks/sequencer/recipes/create-multichannel-sequence.ts

@@ -0,0 +1,51 @@
+/**
+ * @title Create a draft sequence with email, LinkedIn and a call
+ * @when Building outreach. Creating the draft is tier `external` in the contract but contacts nobody; the
+ * LAUNCH is what reaches people (see launch-and-enroll.ts). Three rules the API only enforces at send time:
+ * 1) an EMAIL step needs `input_type: "MANUAL_TEMPLATE"` or its subject/body are ignored; 2) a LinkedIn
+ * (HEYREACH) step needs `linkedin_action_type` and the action's own copy key, never `body`; 3) `time_interval`
+ * is in SECONDS. Attach the sender mailbox as a channel; LinkedIn steps also need a LinkedIn sender (app).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const DAY = 86400;
+
+export async function createDraftSequence(name: string, listId: number, mailbox: { id: number; email: string }) {
+  const created = await g8.api.sequenceLifecycle.createSequence({
+    body: {
+      name,
+      associated_list_id: listId,
+      finish_on_reply: true,
+      steps: [
+        {
+          step_order: 1,
+          step_type: "EMAIL",
+          input_type: "MANUAL_TEMPLATE",
+          time_interval: 0,
+          step_data: {
+            subject: "{{Quick question|One idea}} for {{company}}",
+            body: "Hi {{first_name}},\n\nI noticed {{company}} is growing. Worth a chat?",
+          },
+        },
+        {
+          step_order: 2,
+          step_type: "HEYREACH",
+          input_type: "MANUAL_TEMPLATE",
+          time_interval: 2 * DAY,
+          step_data: { linkedin_action_type: "CONNECTION_REQUEST", linkedin_connection_message: "Hi {{first_name}}, I'd love to connect." },
+        },
+        {
+          step_order: 3,
+          step_type: "PHONE",
+          input_type: "MANUAL_TEMPLATE",
+          time_interval: 3 * DAY,
+          step_data: { dial_dnc: false, phone_options: ["mobile", "direct"] },
+        },
+      ],
+      channels: [{ channel_id: mailbox.id, channel_value: mailbox.email, channel_type: "SMTP" }],
+    },
+  });
+  return created.data?.id;
+}

package/blocks/sequencer/recipes/launch-and-enroll.ts

@@ -0,0 +1,44 @@
+/**
+ * @title Check a draft, launch it, and enroll contacts
+ * @when Starting outreach. Both `runSequence` and `addContactsToSequence` are tier `external`: they reach real
+ * people, so a human must approve the recipient count first. `previewSequence` is free and tells you whether the
+ * copy will send as shown. Re-running after a failure is safe: the launch is skipped unless the sequence is still a draft, and enrollment uses a key
+ * derived from the sequence and contact ids and is idempotent anyway (already-enrolled contacts are skipped) and needs BOTH
+ * `contact_ids` and the `list_id` they came from. Contacts must be in a list already: search results are masked
+ * until saved.
+ */
+import { createHash } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function launchAndEnroll(sequenceId: string, listId: number, contactIds: number[], humanApproved: boolean) {
+  if (!humanApproved) throw new Error(`Refusing to contact ${contactIds.length} people without approval`);
+
+  const verdict = await g8.api.deliverability.getSafeToSend();
+  if ((verdict.data as { safe_to_send?: boolean } | undefined)?.safe_to_send === false)
+    throw new Error("Deliverability says not safe to send right now");
+
+  const preview = await g8.api.sequenceLifecycle.previewSequence({ path: { sequence_id: sequenceId } });
+  const issues = (preview.data as { content_issues?: unknown[]; will_send_as_shown?: boolean } | undefined)?.content_issues ?? [];
+  if (issues.length) throw new Error(`Fix the copy first: ${JSON.stringify(issues)}`);
+
+  const current = await g8.api.sequences.getSequence({ path: { sequence_id: sequenceId } });
+  const status = (current.data as { status?: string } | undefined)?.status;
+  // Launch ONLY a draft. "live" has several spellings (live, waiting, running, active) and there are transitional
+  // states (scheduling, resuming): anything that is not a draft must not be launched again.
+  const isDraft = ["drafted", "draft"].includes((status ?? "").toLowerCase());
+  const launched = isDraft
+    ? await g8.api.sequences.runSequence({ path: { sequence_id: sequenceId } })
+    : { data: { status, skipped: "not a draft, so it was not launched again" } };
+  const enrolled = await g8.api.sequences.addContactsToSequence(
+    { path: { sequence_id: sequenceId }, body: { contact_ids: contactIds, list_id: listId } },
+    {
+      idempotencyKey: createHash("sha256")
+        .update(`${sequenceId}|${listId}|${[...contactIds].sort((a, b) => a - b).join(",")}`)
+        .digest("hex")
+        .slice(0, 40),
+    },
+  );
+  return { launched: launched.data, enrolled: enrolled.data };
+}

package/blocks/sequencer/recipes/pause-when-unsafe.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Pause live sequences when deliverability turns bad
+ * @when A scheduled guard. `pauseSequence` is tier `external` (it changes who is being contacted): run it
+ * only under a standing instruction from the human. Pausing keeps every contact's place; `resumeSequence`
+ * continues. Skips sequences that are already paused or still in a transitional status.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function pauseIfUnsafe() {
+  const verdict = await g8.api.deliverability.getSafeToSend();
+  if ((verdict.data as { safe_to_send?: boolean } | undefined)?.safe_to_send !== false) return [];
+
+  const paused: string[] = [];
+  const seen = new Set<string>();
+  // Pausing takes a sequence out of the "live" filter, so page 1 keeps showing the rest. Stop when a page
+  // brings nothing new (pauses still settling) so this cannot loop forever.
+  for (;;) {
+    const live = await g8.api.sequences.listSequences({ query: { status: "live", limit: 100, page: 1 } });
+    const fresh = (live.data ?? []).filter((seq) => !seen.has(seq.id));
+    if (fresh.length === 0) break;
+    for (const seq of fresh) {
+      seen.add(seq.id);
+      await g8.api.sequences.pauseSequence({ path: { sequence_id: seq.id } });
+      paused.push(seq.id);
+    }
+  }
+  return paused;
+}

package/blocks/sequencer/recipes/sequence-report.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Report how a sequence is doing
+ * @when A daily digest or an agent deciding whether to pause. Reads only. `step_stats` gives per-step counts by
+ * state; `skip_reason_breakdown` is counted once per contact, so do NOT expect it to equal the sum of the
+ * per-step skipped counts.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function sequenceReport(sequenceId: string) {
+  const [stats, analytics] = await Promise.all([
+    g8.api.sequences.getSequenceStats({ path: { sequence_id: sequenceId } }),
+    g8.api.sequenceLifecycle.getSequenceAnalytics({ path: { sequence_id: sequenceId } }),
+  ]);
+  return {
+    contacts: stats.data?.total_contacts ?? 0,
+    steps: stats.data?.step_stats ?? [],
+    skipped: stats.data?.skip_reason_breakdown ?? {},
+    overview: analytics.data?.overview ?? {},
+  };
+}

package/blocks/social-ads/README.md

@@ -0,0 +1,128 @@
+# social-ads
+
+Publish to social, watch your ads, make ad creatives and feed ad platforms with your lists. Builds on `lists`
+(the list picker for audience syncs).
+
+Install: `npx @graph8/sdk add social-ads` (installs `foundation`, `crm` and `lists` first).
+
+## What you get
+
+| Component | Use it for | Props |
+|---|---|---|
+| `PostComposer` | Write a post, draft with AI, save, schedule or publish | `onSaved(post, action)` |
+| `SocialPostList` | Posts by status; publish, cancel a scheduled post, delete | `refreshKey`, `pageSize` |
+| `AdCampaignList` | Campaigns with budget, dates, results; refresh status, retry launch, delete | `refreshKey` |
+| `CreativeGallery` | Generate, follow, edit and organize AI ad creatives | `status` |
+| `AudienceSync` | Send a list to Meta / LinkedIn / Google / X, push, pause, launch a campaign | `onLaunched` |
+
+Hook `useSocialAccounts()`; helpers in `lib/social-ads-types.ts` (time helpers `localInputToIso`, `formatInstant`, `formatDateOnly`).
+
+## Everything that publishes or launches is confirmed
+
+Publishing and launching are the `external` tier: they reach real people or spend on an ad account, and cannot be recalled from here.
+
+| Action | Tier | What the confirmation says |
+|---|---|---|
+| AI post drafts, ad creative generation, new creative image | billable | credits are used; **no advance price and no balance read** |
+| Schedule a post | external | the account and the exact instant, with the time zone name |
+| Publish now | external | the account; goes live immediately |
+| Create an audience sync | external | the platform and the list size (people sent) |
+| Push now / pause / resume a sync | external | which platform and what it does (the size is not known for an existing sync) |
+| Launch a campaign | external | the platform and the daily budget; the spend is billed by the ad platform, not graph8 credits |
+| Refresh or retry a campaign | external | which platform is asked |
+| Cancel a scheduled post, delete a post, creative or sync | destructive | what is removed; a 404 on delete counts as done |
+| Delete an ad campaign | destructive | **stops the live campaign on the platform first**, then removes it; a 502 means the platform refused and the campaign is still live and spending |
+
+## Time
+
+A scheduled post is an instant. `PostComposer` takes a wall-clock time in the viewer's zone (`datetime-local`), sends the UTC instant
+(`new Date(local).toISOString()`), and every screen shows instants in the viewer's zone with its name ("9:00 AM PDT"). Campaign start and end
+are **date-only**: send `YYYY-MM-DD` as typed, show them with `formatDateOnly` (UTC) so a date never slides a day.
+
+## The flow, with the ids that pass between steps
+
+1. `GET /social/accounts` -> an account `id` = `account_ref`. Empty means a person must connect LinkedIn in graph8 first (browser sign-in, no API).
+2. `POST /social/posts/generate { instructions, variants }` (billable, saves nothing) -> `variants[].body`.
+3. `POST /social/posts { body, account_ref, idempotency_key }` -> a DRAFT with `id`. The composer keeps that id: a retry after step 4 failed PATCHes it, never creates a second.
+4. `POST /social/posts/{id}/schedule { scheduled_at }` or `/publish` (external). Poll `GET /social/posts/{id}` until `live` or `failed`; the list shows it.
+5. Ads: connect ad accounts in graph8 (app only). `POST /audience-syncs { audience_id, platform }` -> sync `id` (409 if that pair exists) -> `POST /audience-syncs/{id}/launch { name, daily_budget, destination_url, ... }`
+   -> a campaign in `GET /ad-campaigns` whose `platform_campaign_id` joins the rows of `GET /ad-campaigns/metrics` (one sync can have several campaigns; `sync_config_id` alone would sum them all).
+   **A refused launch is HTTP 200 with `status: "error"` and a `message` in the body**, never a success: `launchOutcome` reads it. Retry behaves the same.
+6. Creatives: `GET /ad-creatives/specs` -> `POST /ad-creatives { platform, ad_format, prompt }` (201, `generating`) -> the list re-reads while any card generates -> `POST .../move-to-gallery`.
+
+```tsx
+"use client";
+import { useState } from "react";
+import { PostComposer } from "@/components/g8/social-ads/post-composer";
+import { SocialPostList } from "@/components/g8/social-ads/social-post-list";
+
+export function Social() {
+  const [tick, setTick] = useState(0);
+  return (<div className="grid gap-6 md:grid-cols-2"><PostComposer onSaved={() => setTick(tick + 1)} /><SocialPostList refreshKey={tick} /></div>);
+}
+```
+
+(`add` flattens `components/` into `components/g8/social-ads/`; adjust the alias to your app.)
+
+## Prerequisites (a human must do these)
+
+- `lists-installed` (app); `proxy-allowlist` (app): `social`, `ad-campaigns`, `ad-creatives`, `audience-syncs`, `lists`.
+- `social-account` (api): a LinkedIn account connected in graph8 (Settings, Channels).
+- `ad-accounts` (api): each ad platform connected in graph8 through its sign-in.
+- `credits` (api): for AI drafts and creatives.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Account a post uses | the first connected account |
+| AI drafts per request | 3 |
+| Sync mode and cadence | mirror, every 24 hours |
+
+Ask the person: campaign daily budget, dates and destination URL (always typed by them), and who may publish, sync or launch (the proxy's `authorize`).
+`listSyncRuns` is a plain read that the contract grades `billable`; it is used by recipes only, not by a component.
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/schedule-post.ts` | Accounts, AI drafts, create a draft, schedule or publish, wait until live |
+| `recipes/creative-to-gallery.ts` | Specs, create a creative, poll, edit copy, move to the gallery |
+| `recipes/sync-audience-and-launch.ts` | Sync a list, push, launch a campaign, read results by campaign |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| cancelSocialPost | POST /social/posts/{post_id}/cancel | destructive | SocialPostList |
+| createAdCreative | POST /ad-creatives | billable | CreativeGallery |
+| createAudienceSync | POST /audience-syncs | external | AudienceSync |
+| createSocialPost | POST /social/posts | write | PostComposer |
+| deleteAdCampaign | DELETE /ad-campaigns/{campaign_id} | destructive | AdCampaignList |
+| deleteAdCreative | DELETE /ad-creatives/{creative_id} | destructive | CreativeGallery |
+| deleteAudienceSync | DELETE /audience-syncs/{config_id} | destructive | AudienceSync |
+| deleteSocialPost | DELETE /social/posts/{post_id} | destructive | SocialPostList |
+| generateSocialPost | POST /social/posts/generate | billable | PostComposer |
+| getAdCreativeSpecs | GET /ad-creatives/specs | read | CreativeGallery |
+| getAdCreativeStatus | GET /ad-creatives/{creative_id}/status | read | recipes |
+| getPerCampaignMetrics | GET /ad-campaigns/metrics | read | AdCampaignList |
+| getSocialPost | GET /social/posts/{post_id} | read | recipes |
+| launchAdCampaign | POST /audience-syncs/{config_id}/launch | external | AudienceSync |
+| listAdCampaigns | GET /ad-campaigns | read | AdCampaignList |
+| listAdCreatives | GET /ad-creatives | read | CreativeGallery |
+| listAudienceSyncs | GET /audience-syncs | read | AudienceSync |
+| listSocialAccounts | GET /social/accounts | read | PostComposer, useSocialAccounts |
+| listSocialPosts | GET /social/posts | read | SocialPostList |
+| listSyncErrors | GET /audience-syncs/{config_id}/errors | read | AudienceSync |
+| listSyncRuns | GET /audience-syncs/{config_id}/runs | billable | recipes |
+| moveAdCreativeToGallery | POST /ad-creatives/{creative_id}/move-to-gallery | write | CreativeGallery |
+| publishSocialPost | POST /social/posts/{post_id}/publish | external | PostComposer, SocialPostList |
+| refreshAllCampaignStatuses | POST /ad-campaigns/status-refresh | external | AdCampaignList |
+| refreshCampaignStatus | POST /ad-campaigns/{campaign_id}/status-refresh | external | AdCampaignList |
+| regenerateAdCreativeImage | POST /ad-creatives/{creative_id}/regenerate-image | billable | CreativeGallery |
+| retryCampaignLaunch | POST /ad-campaigns/{campaign_id}/retry | external | AdCampaignList |
+| scheduleSocialPost | POST /social/posts/{post_id}/schedule | external | PostComposer |
+| triggerAudienceSync | POST /audience-syncs/{config_id}/trigger | external | AudienceSync |
+| updateAdCreative | PATCH /ad-creatives/{creative_id} | write | CreativeGallery |
+| updateAudienceSync | PATCH /audience-syncs/{config_id} | external | AudienceSync |
+| updateSocialPost | PATCH /social/posts/{post_id} | write | PostComposer |