@graph8/sdk 0.308.1 → 0.357.0

package/blocks/block.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://graph8.com/schemas/sdk-block.schema.json",
+  "title": "graph8 SDK block manifest",
+  "description": "blocks/<dir>/block.json. A block is editable source (components, hooks, server recipes) that a coding agent copies into a customer app with `npx @graph8/sdk add <block>`. `operations`, component `tiers` and `scopes` are DERIVED from the API contract and verified by CI, never trusted.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "summary", "features", "dependsOn", "operations", "components", "hooks", "recipes", "prerequisites", "scopes", "defaults", "peerDependencies"],
+  "$defs": {
+    "blockId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" },
+    "operationId": { "type": "string", "pattern": "^[a-z0-9_]+$" },
+    "relativeFile": { "type": "string", "pattern": "^(components|hooks|lib|server|recipes)/[A-Za-z0-9._/-]+\\.(ts|tsx)$" },
+    "tier": { "enum": ["read", "write", "billable", "external", "destructive"] },
+    "operations": { "type": "array", "items": { "$ref": "#/$defs/operationId" }, "uniqueItems": true }
+  },
+  "properties": {
+    "$schema": { "type": "string" },
+    "id": { "$ref": "#/$defs/blockId" },
+    "title": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\n]+$", "description": "One line for agent catalogs." },
+    "features": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "dependsOn": { "type": "array", "items": { "$ref": "#/$defs/blockId" }, "uniqueItems": true },
+    "operations": { "$ref": "#/$defs/operations", "description": "Contract operationIds this block uses (key of API_OPERATIONS)." },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "file", "purpose", "operations", "tiers"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[A-Z][A-Za-z0-9]*$" },
+          "file": { "$ref": "#/$defs/relativeFile" },
+          "purpose": { "type": "string", "minLength": 1 },
+          "operations": { "$ref": "#/$defs/operations", "description": "Subset of the block's operations." },
+          "tiers": { "type": "array", "items": { "$ref": "#/$defs/tier" }, "uniqueItems": true, "description": "DERIVED: the distinct tiers of `operations`, in order read, write, billable, external, destructive." }
+        }
+      }
+    },
+    "hooks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "file", "purpose"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^use[A-Z][A-Za-z0-9]*$" },
+          "file": { "$ref": "#/$defs/relativeFile" },
+          "purpose": { "type": "string", "minLength": 1 },
+          "operations": { "$ref": "#/$defs/operations" }
+        }
+      }
+    },
+    "lib": {
+      "type": "array",
+      "description": "Plain modules (clients, helpers) that are neither components nor hooks.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "purpose"],
+        "properties": { "file": { "$ref": "#/$defs/relativeFile" }, "purpose": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "server": {
+      "type": "array",
+      "description": "Server-only files (route handlers, proxies). `target` is where the CLI installs it in the customer app; omitted means under g8/<file>.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "purpose"],
+        "properties": {
+          "file": { "$ref": "#/$defs/relativeFile" },
+          "purpose": { "type": "string", "minLength": 1 },
+          "target": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "recipes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "title", "when"],
+        "properties": {
+          "file": { "$ref": "#/$defs/relativeFile" },
+          "title": { "type": "string", "minLength": 1 },
+          "when": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "prerequisites": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "description", "where", "verify"],
+        "properties": {
+          "id": { "$ref": "#/$defs/blockId" },
+          "description": { "type": "string", "minLength": 1 },
+          "where": { "enum": ["app", "api"], "description": "app: something in the customer's codebase/env. api: something in the graph8 workspace." },
+          "verify": { "type": "string", "minLength": 1, "description": "How the agent proves it is satisfied (a command, a call, a file to look for)." }
+        }
+      }
+    },
+    "scopes": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z_]+:[a-z_]+$" },
+      "uniqueItems": true,
+      "description": "DERIVED: API key scopes the operations need, sorted."
+    },
+    "defaults": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["decision", "default", "askHuman"],
+        "properties": {
+          "decision": { "type": "string", "minLength": 1 },
+          "default": { "type": "string", "minLength": 1 },
+          "askHuman": { "type": "boolean", "description": "true: the agent must ask the person before using the default." }
+        }
+      }
+    },
+    "peerDependencies": {
+      "type": "object",
+      "description": "npm packages the block's source imports (besides @graph8/sdk), with a version range.",
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "stacks": { "type": "array", "items": { "$ref": "#/$defs/blockId" }, "uniqueItems": true, "description": "Stack ids this block is part of (informational; stacks/<id>.json is authoritative)." }
+  }
+}

package/blocks/block.types.ts

@@ -0,0 +1,109 @@
+/**
+ * TypeScript shape of `blocks/<dir>/block.json` and `stacks/<id>.json`.
+ * The JSON Schemas (`block.schema.json`, `stacks/stack.schema.json`) are the
+ * enforced contract; these types mirror them for tooling (the CLI, validators).
+ */
+
+export type Tier = "read" | "write" | "billable" | "external" | "destructive";
+
+/** Display and comparison order for tiers: least to most consequential. */
+export const TIER_ORDER: readonly Tier[] = ["read", "write", "billable", "external", "destructive"];
+
+export interface BlockComponent {
+  /** PascalCase export name. */
+  name: string;
+  /** Path inside the block directory, for example `components/contacts-table.tsx`. */
+  file: string;
+  purpose: string;
+  /** Contract operationIds this component calls. A subset of the block's `operations`. */
+  operations: string[];
+  /** DERIVED from the contract: distinct tiers of `operations`, in TIER_ORDER. */
+  tiers: Tier[];
+}
+
+export interface BlockHook {
+  name: string;
+  file: string;
+  purpose: string;
+  operations?: string[];
+}
+
+export interface BlockFile {
+  file: string;
+  purpose: string;
+}
+
+export interface BlockServerFile extends BlockFile {
+  /** Where the CLI installs it in the customer app (default: `g8/<file>`). */
+  target?: string;
+}
+
+export interface BlockRecipe {
+  file: string;
+  title: string;
+  when: string;
+}
+
+export interface BlockPrerequisite {
+  id: string;
+  description: string;
+  /** `app`: the customer's codebase or env. `api`: the graph8 workspace. */
+  where: "app" | "api";
+  verify: string;
+}
+
+export interface BlockDefault {
+  decision: string;
+  default: string;
+  /** true: the agent must ask the person before using the default. */
+  askHuman: boolean;
+}
+
+export interface BlockManifest {
+  $schema?: string;
+  id: string;
+  title: string;
+  /** One line for agent catalogs. */
+  summary: string;
+  features: string[];
+  /** Block ids. Every block except `foundation` depends on it, directly or transitively. */
+  dependsOn: string[];
+  /** Contract operationIds (keys of API_OPERATIONS). */
+  operations: string[];
+  components: BlockComponent[];
+  hooks: BlockHook[];
+  lib?: BlockFile[];
+  server?: BlockServerFile[];
+  recipes: BlockRecipe[];
+  prerequisites: BlockPrerequisite[];
+  /** DERIVED from the contract: sorted, distinct API key scopes of `operations`. */
+  scopes: string[];
+  defaults: BlockDefault[];
+  /** npm packages the source imports besides `@graph8/sdk`, with a version range. */
+  peerDependencies: Record<string, string>;
+  stacks?: string[];
+}
+
+export interface StackNavItem {
+  label: string;
+  /** Route in the customer app, for example `/contacts`. */
+  path: string;
+  /** Block id that owns the screen. */
+  block: string;
+  /** Component name (from that block's `components`) that renders it. */
+  component: string;
+  /** JSON props passed to the component on its route (for a component that needs input to render anything). */
+  props?: Record<string, unknown>;
+}
+
+export interface StackManifest {
+  $schema?: string;
+  id: string;
+  title: string;
+  summary: string;
+  /** `planned` while some blocks are still being built: CI skips the references and `create` refuses. Default `available`. */
+  status?: "available" | "planned";
+  /** Install order: each block's `dependsOn` come earlier. */
+  blocks: string[];
+  nav: StackNavItem[];
+}

package/blocks/campaigns/README.md

@@ -0,0 +1,118 @@
+# campaigns
+
+The AI campaign builder: set the company profile the AI writes from, define ICPs and buyer personas, generate
+campaign ideas, then create a campaign, attach an audience, build its steps and copy, and launch it. The
+Apollo / HubSpot "campaigns" screen, with generation behind credit confirmations.
+
+Depends on: `lists` (the audience picker), `mailboxes` (senders and the connect-a-mailbox link). Install:
+`npx @graph8/sdk add campaigns`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `IcpEditor` | Company profile (edit, build with AI, approve) plus ICPs: add, edit, archive. | read, write, billable, destructive |
+| `PersonaEditor` | Buyer personas: add, edit, archive, or have AI suggest a set and accept the ones you want. | read, write, billable, destructive |
+| `CampaignWizard` | A page. Idea (AI, polled) -> create -> audience -> steps -> launch. Also exports the three step components below. | all |
+| `CampaignAudienceStep` | Attach or detach a contact list (uses the lists block `ListPicker`; reads `getCampaignFull`, since `getCampaign` omits the audience). | read, write, external |
+| `CampaignSequenceStep` | Add, edit, remove and AI-write sequence steps. | read, billable, external, destructive |
+| `CampaignLaunchStep` | Readiness checklist, sender choice, deliverability warning, confirmed launch. | read, external |
+| `CampaignList` | A page. All campaigns; open one for metrics and documents; delete. | read, billable, external, destructive |
+| `CampaignAssets` | Campaign documents: read, edit, rewrite with AI, add, delete. Standalone: shows a campaign picker. | read, billable, external, destructive |
+| `CampaignMetrics` | A page. Metrics for 7, 30, 90 or 365 days. Standalone: shows a campaign picker. | read |
+
+Page components with no required props (use them as nav pages): `CampaignWizard`, `CampaignList`,
+`CampaignMetrics`, `CampaignAssets`, `IcpEditor`, `PersonaEditor`.
+
+Every billable, external or destructive call opens `ConfirmSpendDialog` first. There is no price or balance
+read, so credit numbers are estimates: edit `CREDIT_ESTIMATES` in `lib/campaigns-utils.ts`. Note that
+`createCampaign`, `updateCampaign`, step and document writes and `attachAudienceToCampaign` are tier
+`external` in the contract although they message nobody; only `launchCampaign` starts outreach.
+
+## The flow, in order
+
+1. **Company profile.** `IcpEditor` -> `getCompanyProfile` -> `updateCompanyProfile` with the real
+   `website_url` (replaces the stored field set; an approved profile needs `unapprove_if_approved`).
+   Optionally `generateCompanyProfile` (billable), poll `getCompanyProfileWorkflowStatus`, then
+   `approveCompanyProfile` (locks it).
+2. **ICP and personas.** `createIcp`, `createPersona` (both need the profile's `website_url`), or
+   `recommendCampaignPersonas` (billable; it only RETURNS suggestions and saves nothing, so create the ones you keep with `createPersona`). Archive is a soft delete.
+3. **Ideas.** `generateCampaignIdeasAsync` (billable) -> `task_id` -> poll `getCampaignIdeasTaskStatus` every
+   2-3 seconds until `completed`; `ideas[]` carry `campaign_name`, `core_concept`, `primary_hook`.
+4. **Create.** `createCampaign` -> `id`. Store it at once; later steps reuse it and "Create" becomes
+   "Save changes" (`updateCampaign`). With `auto_generate_documents` the documents generate in the
+   background: poll `getCampaignGenerationStatus`.
+5. **Audience.** `getCampaignFull` shows what is attached (`audience_list_id`, `audience`). `ListPicker` (lists block) -> a list `id` -> `attachAudienceToCampaign` with `list_id` as a
+   string. Build the list in the search/lists blocks first.
+6. **Steps and copy.** `getCampaignSequence` -> `createCampaignStep` (channel -> mode matrix: email -> email,
+   phone -> call|voicemail, sms -> sms, social -> connect_note|dm|comment|reply) -> `generateCampaignStepContent`
+   (billable) per step. `CampaignAssets` edits the documents behind them.
+7. **Launch.** `CampaignLaunchStep` -> `getCampaignFull` (audience attached with its size, >= 1 step, `is_launched`),
+   `listMailboxes` (active ones), `getSafeToSend` (a warning) -> `launchCampaign` with `sender_mailbox_ids`.
+   The one-step launch executes email only; configure other channels in the sequencer block.
+8. **Measure.** `CampaignMetrics` -> `getCampaignMetrics` with `days`.
+
+## Prerequisites
+
+- A company profile with the real website (`where: "api"`).
+- An ACTIVE email mailbox. Google and Microsoft mailboxes are connected by the person in the graph8 app
+  (`where: "app"`); the API cannot run OAuth consent.
+- A contact list to message (lists block). Search results are masked until saved to a list.
+- Credits for AI generation (`where: "api"`); a 402 means insufficient credits.
+
+## Defaults (do not ask the human)
+
+- 5 ideas, goal `awareness`, channel `email`, no auto-generated documents (generate per step so each spend is
+  confirmed), sender = the first active mailbox.
+- **Ask the human**: whether to launch and to which list (state the recipient count), and whether to approve
+  (lock) the company profile.
+
+## Failure notes
+
+- Launch can answer 502 `draft_created_activation_failed` or `activation_state_uncertain`: a sequence may
+  exist. Check it before retrying; the block shows this warning and never auto-retries.
+- Document and step edits that fail with 404 on delete count as done.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `get_company_profile_company_profile_get` | GET /company-profile | read | IcpEditor, PersonaEditor, CampaignWizard |
+| `update_company_profile_company_profile_put` | PUT /company-profile | write | IcpEditor |
+| `generate_company_profile_company_profile_generate_post` | POST /company-profile/generate | billable | IcpEditor |
+| `get_company_profile_workflow_status_company_profile_workflow_status_get` | GET /company-profile/workflow-status | read | IcpEditor |
+| `approve_company_profile_company_profile_approve_post` | POST /company-profile/approve | write | IcpEditor |
+| `list_icps_icps_get` | GET /icps | read | IcpEditor |
+| `create_icp_icps_post` | POST /icps | write | IcpEditor |
+| `update_icp_icps__icp_id__patch` | PATCH /icps/{icp_id} | write | IcpEditor |
+| `archive_icp_icps__icp_id__archive_post` | POST /icps/{icp_id}/archive | destructive | IcpEditor |
+| `list_personas_personas_get` | GET /personas | read | PersonaEditor, CampaignWizard |
+| `create_persona_personas_post` | POST /personas | write | PersonaEditor |
+| `update_persona_personas__persona_id__patch` | PATCH /personas/{persona_id} | write | PersonaEditor |
+| `archive_persona_personas__persona_id__archive_post` | POST /personas/{persona_id}/archive | destructive | PersonaEditor |
+| `recommend_campaign_personas_campaigns_recommend_personas_post` | POST /campaigns/recommend-personas | billable | PersonaEditor |
+| `generate_campaign_ideas_async_campaigns_generate_ideas_async_post` | POST /campaigns/generate-ideas-async | billable | CampaignWizard |
+| `get_campaign_ideas_task_status_campaigns_ideas_status__task_id__get` | GET /campaigns/ideas/status/{task_id} | read | CampaignWizard |
+| `create_campaign_campaigns_post` | POST /campaigns | external | CampaignWizard |
+| `update_campaign_campaigns__campaign_id__patch` | PATCH /campaigns/{campaign_id} | external | CampaignWizard |
+| `get_campaign_generation_status_campaigns__campaign_id__status_get` | GET /campaigns/{campaign_id}/status | read | CampaignWizard |
+| `get_campaign_full_campaigns__campaign_id__full_get` | GET /campaigns/{campaign_id}/full | read | CampaignWizard, CampaignAudienceStep, CampaignLaunchStep |
+| `attach_audience_to_campaign_campaigns__campaign_id__audience_put` | PUT /campaigns/{campaign_id}/audience | external | CampaignWizard, CampaignAudienceStep |
+| `get_campaign_sequence_campaigns__campaign_id__sequence_get` | GET /campaigns/{campaign_id}/sequence | read | CampaignWizard, CampaignSequenceStep |
+| `create_campaign_step_campaigns__campaign_id__sequence_steps_post` | POST /campaigns/{campaign_id}/sequence/steps | external | CampaignWizard, CampaignSequenceStep |
+| `update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put` | PUT /campaigns/{campaign_id}/sequence/steps/{step_id} | external | CampaignWizard, CampaignSequenceStep |
+| `delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete` | DELETE /campaigns/{campaign_id}/sequence/steps/{step_id} | destructive | CampaignWizard, CampaignSequenceStep |
+| `generate_campaign_step_content_campaigns__campaign_id__sequence_steps__step_id__generate_post` | POST /campaigns/{campaign_id}/sequence/steps/{step_id}/generate | billable | CampaignWizard, CampaignSequenceStep |
+| `list_mailboxes_mailboxes_get` | GET /mailboxes | read | CampaignWizard, CampaignLaunchStep |
+| `get_safe_to_send_deliverability_safe_to_send_get` | GET /deliverability/safe-to-send | read | CampaignWizard, CampaignLaunchStep |
+| `launch_campaign_campaigns__campaign_id__launch_post` | POST /campaigns/{campaign_id}/launch | external | CampaignWizard, CampaignLaunchStep |
+| `list_campaigns_campaigns_get` | GET /campaigns | read | CampaignList |
+| `delete_campaign_campaigns__campaign_id__delete` | DELETE /campaigns/{campaign_id} | destructive | CampaignList |
+| `list_campaigns_for_picker_campaigns_picker_get` | GET /campaigns/picker | read | CampaignList, CampaignAssets, CampaignMetrics, CampaignSelect |
+| `get_campaign_metrics_campaigns__campaign_id__metrics_get` | GET /campaigns/{campaign_id}/metrics | read | CampaignList, CampaignMetrics |
+| `list_campaign_documents_campaigns__campaign_id__documents_get` | GET /campaigns/{campaign_id}/documents | read | CampaignList, CampaignAssets |
+| `get_campaign_document_campaigns__campaign_id__documents__document_id__get` | GET /campaigns/{campaign_id}/documents/{document_id} | read | CampaignList, CampaignAssets |
+| `create_campaign_document_campaigns__campaign_id__documents_post` | POST /campaigns/{campaign_id}/documents | external | CampaignList, CampaignAssets |
+| `update_campaign_document_campaigns__campaign_id__documents__document_id__put` | PUT /campaigns/{campaign_id}/documents/{document_id} | external | CampaignList, CampaignAssets |
+| `delete_campaign_document_campaigns__campaign_id__documents__document_id__delete` | DELETE /campaigns/{campaign_id}/documents/{document_id} | destructive | CampaignList, CampaignAssets |
+| `regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post` | POST /campaigns/{campaign_id}/documents/{document_id}/regenerate | billable | CampaignList, CampaignAssets |