@graph8/sdk 0.370.0 → 0.374.0

package/blocks/pages/components/seo-report.tsx

@@ -26,6 +26,7 @@ import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { EmptyState } from "@/g8/components/empty-state";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { asRec, num, rowsOf, shortDate, text } from "../lib/studio";
@@ -110,12 +111,15 @@ function Keywords({ domain }: { domain: string }) {
   );
 }
 
+/** The audits API has no paging: a full read is announced under the audit chips. */
+const AUDIT_LIMIT = 10;
+
 export function SeoReport({ defaultDomain = "", className }: SeoReportProps) {
   const [domain, setDomain] = useState(defaultDomain);
   const [maxPages, setMaxPages] = useState(100);
   const [confirm, setConfirm] = useState(false);
   const [selected, setSelected] = useState<string | null>(null);
-  const audits = useG8Query((signal) => g8Get("/seo/audits", { limit: 10 }, { signal }), []);
+  const audits = useG8Query((signal) => g8Get("/seo/audits", { limit: AUDIT_LIMIT }, { signal }), []);
   const start = useG8Mutation(() => g8Post("/seo/audits", { domain: domain.trim(), max_pages: maxPages }), {
     onSuccess: (res) => {
       setConfirm(false);
@@ -143,6 +147,7 @@ export function SeoReport({ defaultDomain = "", className }: SeoReportProps) {
               {text(a.domain)} · {shortDate(a.created_at)}
             </Button>
           ))}
+          <FirstNotice className="w-full" shown={rows.length} limit={AUDIT_LIMIT} noun="audits" />
         </div>
       ) : null}
       <div className="space-y-4">

package/blocks/pages/hooks/use-landing-page-paths.ts

@@ -0,0 +1,60 @@
+"use client";
+
+/**
+ * useLandingPagePaths: which landing page lives at a given website path. Used by glue that links a page in analytics to
+ * its landing page (web-analytics: "Open landing page").
+ *
+ * A page is matched by its published address only: the path of `published_url`. The analytics path has no host, so when two
+ * landing pages publish the same path on different domains the path is ambiguous and links to NEITHER (never a guess, and
+ * never a match on the page's name or title). Drafts have no `published_url` and are never matched.
+ *
+ * SDK operations (read, free):
+ *   1. listLandingPages  GET /landing-pages?limit&offset   (every page is read, 100 at a time, with useAllPages)
+ */
+import { useMemo } from "react";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { g8Get } from "@/g8/lib/g8-client";
+import { rowsOf } from "../lib/studio";
+import type { LandingPageRow } from "../lib/studio";
+
+const PAGE = 100;
+
+/** `/pricing/` and `/pricing` are the same page; the root stays `/`. */
+export function normalizePath(path: string): string {
+  const p = path.split(/[?#]/)[0];
+  return p.length > 1 ? p.replace(/\/+$/, "") || "/" : p || "/";
+}
+
+/** path -> landing page id, for published pages whose path is unique among them. */
+export function landingPageIdsByPath(pages: Array<Pick<LandingPageRow, "id" | "published_url">>): Map<string, string> {
+  const seen = new Map<string, string | null>();
+  for (const page of pages) {
+    if (!page.published_url) continue;
+    let path: string;
+    try {
+      path = normalizePath(new URL(page.published_url).pathname);
+    } catch {
+      continue;
+    }
+    seen.set(path, seen.has(path) ? null : page.id);
+  }
+  const out = new Map<string, string>();
+  for (const [path, id] of seen) if (id) out.set(path, id);
+  return out;
+}
+
+export interface LandingPagePaths {
+  /** The id of the one published landing page at this path, or undefined. */
+  resolve: (path: string) => string | undefined;
+  loading: boolean;
+}
+
+export function useLandingPagePaths(): LandingPagePaths {
+  const pages = useAllPages<LandingPageRow>(async (page, signal) => {
+    const env = await g8Get("/landing-pages", { limit: PAGE, offset: (page - 1) * PAGE }, { signal });
+    const rows = rowsOf<LandingPageRow>(env.data, "landing_pages");
+    return { rows, hasNext: rows.length >= PAGE };
+  }, []);
+  const map = useMemo(() => landingPageIdsByPath(pages.items), [pages.items]);
+  return { resolve: (path) => map.get(normalizePath(path)), loading: pages.loading };
+}

package/blocks/pages/lib/studio.ts

@@ -8,6 +8,8 @@
  * Nothing here knows more than that, so a field the API adds later never breaks a screen.
  */
 
+import type { PaginatedResponse } from "@graph8/sdk";
+
 export type Rec = Record<string, unknown>;
 
 export function asRec(value: unknown): Rec {
@@ -75,3 +77,8 @@ export function liveUrl(data: unknown): string {
   const rec = asRec(data);
   return text(rec.published_url) || text(rec.url) || text(asRec(rec.landing_page).published_url);
 }
+
+/** Wrap rows and the API's "next" marker (a cursor or an offset; null or absent when there is no more) for `usePaginated`. */
+export function pageOf<T>(rows: T[], next: unknown): PaginatedResponse<T> {
+  return { data: rows, pagination: { next_cursor: next == null || next === "" ? null : String(next) } } as unknown as PaginatedResponse<T>;
+}

package/blocks/phone-numbers/README.md

@@ -0,0 +1,74 @@
+# phone-numbers: buy, assign, configure and release numbers
+
+Every phone number the workspace owns, in one finished screen: see them all, search a carrier for new ones, buy one,
+give it to a teammate or a voice agent, change how it answers, watch its usage against the daily limit, register for text
+messaging (A2P 10DLC), and release it. Install with `npx @graph8/sdk add phone-numbers` (depends on `pickers`, for the
+assignee picker). The dialer, sequencer and voice agents all pick numbers from this inventory.
+
+> Buying a number spends credits and real money, releasing one is irreversible, and submitting a text registration
+> reaches the carriers. Each of those opens a confirm dialog first; nothing here buys, releases or submits by itself.
+
+## Screens
+
+- `PhoneNumbersScreen` (`components/phone-numbers-screen.tsx`): no required props.
+  - **Numbers** tab: stat strip (numbers, assigned, unassigned, calls today), search, filters (use, carrier, assignment,
+    status, kept in the URL as `n_use=...`), and the list. The list is paged on the client with **Load more** ("Showing 25
+    of 140 numbers"): the two list endpoints return the whole inventory and take no `limit`, so nothing is silently cut off.
+    A row opens the number beside the list (`?id=%2B14155550123`, add `&view=full` for a full page, `&dtab=usage` for a tab).
+  - **Buy a number** (sheet): choose a carrier, number type, area code, and digits or a city; search is free. Choose a number,
+    say what it is for (dialer, voice AI, personal work phone) and who gets it, then **Buy for about 250 credits** opens the
+    confirm dialog with the price. A 402 says nothing was bought and nothing was charged.
+  - **Add a number you own** (sheet): register a number you already hold with the voice platform. It buys nothing.
+  - **Text registration** tab: the A2P 10DLC status (brand, campaign, carrier feedback), a form that saves a draft, a
+    confirmed **Submit registration**, and **Retry stuck numbers**.
+  - The open number has tabs: **Overview**, **Assign** (MemberPicker, Assign to me, Unassign, Re-sync voice record),
+    **Usage** (calls today against the daily limit, 7-day calls, connect rate, confirmed counter reset), **Settings**
+    (answering mode, Telnyx caller-ID verification, who answers) and **Release** (release, or remove voice routing only).
+  - Slots: `toolbarActions`, `renderRowActions`, `renderDetailActions`, `extraDetailTabs`.
+- Parts you can compose yourself: `PhoneNumberList`, `PhoneNumberDetail`, `NumberSearch`, `AssignNumber`, `NumberSettings`,
+  `NumberUsage`, `ReleaseNumber`, `RegisterOwnedNumber`, `A2pRegistration`, and the `usePhoneNumbers` hook.
+
+## What the API gives, and what it does not
+
+- **There is no "list my phone numbers" operation in the `phoneNumbers` namespace.** The inventory is two reads, merged:
+  `GET /voice/dialer/numbers` (every number except the ones a voice AI agent holds, with usage) and
+  `GET /voice/agent-phone-numbers` (AI-capable numbers and which agent holds each). `usePhoneNumbers` does the merge.
+- **No price read.** Prices on the purchase dialog are estimates: 250 credits held on purchase, then about 250 credits a
+  month in rental. The API reports no rental per number, so the block never labels any number "billable". Numbers the
+  platform provisioned for you (the onboarding receptionist line) are never rental-billed.
+- **No operations for call forwarding, voicemail greetings or ring-group routing.** Settings says so and links to the
+  platform app instead of showing a dead control. Porting a number in is also an app flow.
+- **Admin-only writes.** Reassigning, switching the answering mode and resetting counters are admin-only through the API; a
+  403 is explained on the screen.
+- **Telnyx numbers must be verified as a caller ID** before they can place calls; an unverified one shows as "Cannot dial"
+  and stays out of the dialer rotation. Twilio numbers need nothing.
+
+## Operations
+
+| Flow | Operation | Tier |
+|---|---|---|
+| Inventory | `listDialerNumbers`, `listAgentPhoneNumbers` | read |
+| Search | `searchAvailablePhoneNumbers` | read (free) |
+| Buy | `purchasePhoneNumber` (Idempotency-Key) | **billable**, confirmed |
+| Assign | `updatePhoneAssignee` (CRM + voice), `updateVoiceAssignee` (voice only; `""` clears the voice assignment, the API cannot clear the CRM owner) | write |
+| Answering mode | `updatePhoneCapabilities` (voice AI, dialer), `updateVoiceInboundType` (rep, work phone) | write |
+| Caller ID, who answers | `verifyVoiceCallerId`, `getVoiceAnsweringAgent` | write, read |
+| Register an owned number | `provisionVoiceNumber` | write (buys nothing) |
+| Release | `releasePhoneNumber` | **destructive**, type the number, then confirmed |
+| Remove voice routing | `deleteVoiceNumber` (keeps the number and its carrier bill) | **destructive**, confirmed |
+| Reset counters | `resetVoiceDailyCounts` (every number, lifts the daily cap) | **destructive**, confirmed |
+| Text registration | `getPhoneA2pStatus`, `saveA2pInputs`, `startA2pRegistration`, `reconcileA2pRegistration` | read, write, **external** (submit is confirmed), write |
+
+Scopes: `voice:read`, `voice:write`, `voice:run` (buy, submit A2P), `voice:delete` (release, remove routing, reset
+counters) and `team:read` (the assignee picker).
+
+## Defaults (no need to ask the human)
+
+- Carrier: Twilio (Telnyx is one select away). A new number is an **outbound dialer** number, owned by the identity behind the key unless an assignee is chosen.
+- A number's use maps to the API as: dialer = `dialer: true`; voice AI = `dialer: false`; personal work phone = `dialer: true, work: true`.
+- Answering mode: "Voice AI agent" and "Outbound dialer" go through `update-capabilities`; "Rep answers" and "Personal work phone" go through `inbound-type`. Both rebuild the number's routing, so the change takes a second click on a button that says the number answers nothing for a moment.
+- Releasing needs the number typed first and then a confirm. If the carrier is unknown (a number only the agents list knows), the person chooses it: the wrong carrier releases nothing.
+- Saving A2P details sends the whole object, merged over what was saved, so a field the form does not edit (an address) is never wiped. The form appears only after the saved details loaded.
+
+Recipes (`recipes/`): search and buy (human approval required), assign or clear a rep, audit the inventory (read-only), and
+save A2P details and check registration.

package/blocks/phone-numbers/block.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "phone-numbers",
+  "title": "Phone numbers",
+  "summary": "Phone numbers: list, search and buy numbers, assign them to reps or agents, configure how they answer, check usage and text registration, and release them.",
+  "features": [
+    "every number in one list (dialer and voice agent numbers), searchable and filterable, paged on the client with Load more",
+    "search a carrier for available numbers by area code, digits or city, then buy one behind a confirm dialog that shows the price",
+    "assign a number to a teammate with a picker (or Assign to me), unassign it, re-sync its voice record",
+    "answering mode (voice AI agent, rep, dialer, personal work phone), Telnyx caller-ID verification, who answers",
+    "today's usage against the daily limit, 7-day calls and connect rate, confirmed counter reset",
+    "A2P 10DLC text registration: status, draft details, confirmed submit, retry stuck numbers",
+    "release a number (type it, then confirm) or remove its voice routing only, both confirmed"
+  ],
+  "dependsOn": [
+    "foundation",
+    "pickers"
+  ],
+  "operations": [
+    "delete_voice_number_voice_numbers_delete",
+    "get_my_team_member_team_members_me_get",
+    "get_phone_a2p_status_phone_numbers_a2p_status_get",
+    "get_voice_answering_agent_voice_numbers_answering_agent_get",
+    "list_agent_phone_numbers_voice_agent_phone_numbers_get",
+    "list_dialer_numbers_voice_dialer_numbers_get",
+    "list_team_members_team_members_get",
+    "provision_voice_number_voice_numbers_provision_post",
+    "purchase_phone_number_phone_numbers_purchase_post",
+    "reconcile_a2p_registration_phone_numbers_a2p_reconcile_post",
+    "release_phone_number_phone_numbers_release_post",
+    "reset_voice_daily_counts_voice_numbers_daily_counts_delete",
+    "save_a2p_inputs_phone_numbers_a2p_inputs_post",
+    "search_available_phone_numbers_phone_numbers_search_post",
+    "start_a2p_registration_phone_numbers_a2p_register_post",
+    "update_phone_assignee_phone_numbers_update_assignee_patch",
+    "update_phone_capabilities_phone_numbers_update_capabilities_patch",
+    "update_voice_assignee_voice_numbers_assignee_patch",
+    "update_voice_inbound_type_voice_numbers_inbound_type_patch",
+    "verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post"
+  ],
+  "components": [
+    {
+      "name": "PhoneNumbersScreen",
+      "file": "components/phone-numbers-screen.tsx",
+      "purpose": "The finished Phone numbers page: inventory with stats, search and filters, a detail for each number, buy, add an owned number, and text registration. Composes the parts below.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "PhoneNumberList",
+      "file": "components/phone-number-list.tsx",
+      "purpose": "The numbers as a table, paged on the client with Load more so nothing is cut off silently. Reads nothing itself.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "PhoneNumberDetail",
+      "file": "components/phone-number-detail.tsx",
+      "purpose": "One number in full: Overview, Assign, Usage, Settings and Release tabs, with slots for extra actions and tabs.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "NumberSearch",
+      "file": "components/number-search.tsx",
+      "purpose": "Search a carrier for available numbers, choose one and buy it. The purchase is billable and opens a confirm dialog with the price estimate first.",
+      "operations": [
+        "list_team_members_team_members_get",
+        "purchase_phone_number_phone_numbers_purchase_post",
+        "search_available_phone_numbers_phone_numbers_search_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "AssignNumber",
+      "file": "components/assign-number.tsx",
+      "purpose": "Assign a number to a teammate with a picker or Assign to me, unassign it, or re-sync its voice record.",
+      "operations": [
+        "get_my_team_member_team_members_me_get",
+        "list_team_members_team_members_get",
+        "update_phone_assignee_phone_numbers_update_assignee_patch",
+        "update_voice_assignee_voice_numbers_assignee_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "NumberSettings",
+      "file": "components/number-settings.tsx",
+      "purpose": "Answering mode (voice AI, rep, dialer, work phone), Telnyx caller-ID verification and who answers the number.",
+      "operations": [
+        "get_voice_answering_agent_voice_numbers_answering_agent_get",
+        "update_phone_capabilities_phone_numbers_update_capabilities_patch",
+        "update_voice_inbound_type_voice_numbers_inbound_type_patch",
+        "verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "NumberUsage",
+      "file": "components/number-usage.tsx",
+      "purpose": "Today's calls against the daily limit, 7-day usage and connect rate, and a confirmed reset of today's counters.",
+      "operations": [
+        "reset_voice_daily_counts_voice_numbers_daily_counts_delete"
+      ],
+      "tiers": [
+        "destructive"
+      ]
+    },
+    {
+      "name": "ReleaseNumber",
+      "file": "components/release-number.tsx",
+      "purpose": "Release a number back to the carrier (type the number, then confirm) or remove its voice routing without releasing it. Both are confirmed.",
+      "operations": [
+        "delete_voice_number_voice_numbers_delete",
+        "release_phone_number_phone_numbers_release_post"
+      ],
+      "tiers": [
+        "destructive"
+      ]
+    },
+    {
+      "name": "RegisterOwnedNumber",
+      "file": "components/register-owned-number.tsx",
+      "purpose": "Register a number you already own with the voice platform. Buys nothing.",
+      "operations": [
+        "list_team_members_team_members_get",
+        "provision_voice_number_voice_numbers_provision_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "A2pRegistration",
+      "file": "components/a2p-registration.tsx",
+      "purpose": "A2P 10DLC text-message registration: status, a saved draft of the business details, a confirmed submit and a retry for stuck numbers.",
+      "operations": [
+        "get_phone_a2p_status_phone_numbers_a2p_status_get",
+        "reconcile_a2p_registration_phone_numbers_a2p_reconcile_post",
+        "save_a2p_inputs_phone_numbers_a2p_inputs_post",
+        "start_a2p_registration_phone_numbers_a2p_register_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "usePhoneNumbers",
+      "file": "hooks/use-phone-numbers.ts",
+      "purpose": "Every number of the workspace: the dialer list and the voice agents' numbers read together and merged. Neither endpoint caps or pages, so the whole inventory arrives; a key that cannot read agents still gets the dialer list and the hook says so.",
+      "operations": [
+        "list_agent_phone_numbers_voice_agent_phone_numbers_get",
+        "list_dialer_numbers_voice_dialer_numbers_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/phone-numbers-utils.ts",
+      "purpose": "Row types, the carrier and answering-mode enums, E.164 checks and formatting, the inventory merge, health and A2P tones, price estimates."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-search-and-buy-number.ts",
+      "title": "Search for a number and buy it",
+      "when": "An agent setting up calling for a workspace. The search is free; the purchase spends credits and needs a human to approve it."
+    },
+    {
+      "file": "recipes/02-assign-number-to-rep.ts",
+      "title": "Assign a number to a rep, or clear it",
+      "when": "Onboarding a rep: give them a caller ID, or take a number back from someone who left."
+    },
+    {
+      "file": "recipes/03-audit-numbers.ts",
+      "title": "Audit the inventory: usage, unassigned numbers and text registration",
+      "when": "A health check before a calling campaign; read-only."
+    },
+    {
+      "file": "recipes/04-register-text-messaging.ts",
+      "title": "Save A2P details and check registration",
+      "when": "Before sending texts to US numbers; saving is safe, submitting reaches the carriers and needs approval."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "credits",
+      "description": "Credits for buying a number: 250 are held on purchase, then about 250 a month in rental (estimates; the API has no price read). A 402 means not enough credits and nothing was charged.",
+      "where": "api",
+      "verify": "A test purchase of one number returns 200, or 402 with no charge."
+    },
+    {
+      "id": "admin-key",
+      "description": "Reassigning a number, switching its answering mode and resetting counters are admin-only through the API. A key without that role gets a 403, which the screens explain.",
+      "where": "api",
+      "verify": "PATCH /phone-numbers/update-assignee on a test number returns 200, not 403."
+    },
+    {
+      "id": "voice-scopes",
+      "description": "Key scopes voice:read, voice:write and voice:run (buy, A2P submit), voice:delete (release, remove routing, reset counters) and team:read for the assignee picker.",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists voice:read, voice:write, voice:run, voice:delete and team:read."
+    }
+  ],
+  "scopes": [
+    "team:read",
+    "voice:delete",
+    "voice:read",
+    "voice:run",
+    "voice:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Which carrier to buy from",
+      "default": "Twilio. Telnyx is one select away; a Telnyx number must then be verified as a caller ID before it can dial",
+      "askHuman": false
+    },
+    {
+      "decision": "What a newly bought number is for",
+      "default": "The outbound dialer, unassigned (it is the signed-in key's person unless an assignee is chosen)",
+      "askHuman": false
+    },
+    {
+      "decision": "Buying numbers",
+      "default": "Always behind a confirm dialog with the price estimate and an Idempotency-Key; never automatic",
+      "askHuman": true
+    },
+    {
+      "decision": "Releasing a number",
+      "default": "Needs the number typed and a second confirm; it cannot be undone and the number can be bought by anyone",
+      "askHuman": true
+    },
+    {
+      "decision": "Is a number billable",
+      "default": "The block never labels a number billable: the API reports no rental per number, and numbers the platform provisioned itself (the onboarding receptionist) are never rental-billed. Only the purchase dialog shows a price",
+      "askHuman": false
+    },
+    {
+      "decision": "Call forwarding, voicemail greetings and routing rules",
+      "default": "Not offered: the API has no operations for them. The screen points to the platform app",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}