@graph8/sdk 0.373.0 → 0.374.0

package/blocks/signals/lib/signals-types.ts

@@ -0,0 +1,228 @@
+"use client";
+
+/**
+ * Types, vocabularies and pure helpers for the signals block's social listening part.
+ *
+ * Every response of the social-listeners routes is an OPEN object in the contract, so the row types below follow the
+ * app's own models (social_listener/interfaces/fastapi/listeners_router.py), which the dev API forwards unchanged.
+ * Enums are copied from the request schemas (generated/schemas.ts), not from memory: the API refuses anything else.
+ * A count the channel did not report is null and shown as a dash, never as 0. Calls nothing.
+ */
+
+export type Platform = "x" | "linkedin" | "reddit" | "instagram" | "youtube";
+export type ListenerType = "brand" | "competitor" | "keyword" | "engagement" | "user";
+export type PostStatus = "new" | "reviewed" | "dismissed";
+export type EngagementType = "comment" | "reaction";
+
+export const PLATFORMS: { value: Platform; label: string }[] = [
+  { value: "x", label: "X" },
+  { value: "linkedin", label: "LinkedIn" },
+  { value: "reddit", label: "Reddit" },
+  { value: "instagram", label: "Instagram" },
+  { value: "youtube", label: "YouTube" },
+];
+export const LISTENER_TYPES: { value: ListenerType; label: string; hint: string }[] = [
+  { value: "brand", label: "Brand", hint: "Posts that mention your brand or products." },
+  { value: "competitor", label: "Competitor", hint: "Posts that mention a competitor." },
+  { value: "keyword", label: "Keyword", hint: "Posts that match a search query." },
+  { value: "engagement", label: "Engagement", hint: "Posts from people who look like your buyers." },
+  { value: "user", label: "Account", hint: "Everything one account posts." },
+];
+export const POST_STATUSES: { value: PostStatus; label: string }[] = [
+  { value: "new", label: "New" },
+  { value: "reviewed", label: "Reviewed" },
+  { value: "dismissed", label: "Dismissed" },
+];
+
+/** Minimum the API accepts for a poll interval (seconds). */
+export const MIN_POLL_SEC = 60;
+/** The API's page-size cap for the post and engagement reads. */
+export const PAGE_SIZE = 100;
+
+/**
+ * Credits per language-model pass of an auto-seed or a generated query. The API publishes no price; this is the backend
+ * constant (credit_server `social_listener_brand_query_build`, mirrored in frontend/features/social-listener/social-listener.costs.ts).
+ */
+export const AI_PASS_CREDITS = 5;
+
+export interface Listener {
+  id: string;
+  platform: string;
+  listener_type: string;
+  name: string;
+  query?: string | null;
+  target_handle?: string | null;
+  filters?: Record<string, unknown> | null;
+  poll_interval_sec?: number | null;
+  monthly_credit_cap?: number | null;
+  is_active: boolean;
+  paused_reason?: string | null;
+  last_polled_at?: string | null;
+  source_list_id?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+export interface ListenerDetailData { listener: Listener; match_count?: number | null; credit_burn?: number | null }
+
+export interface MatchedPost {
+  post_external_id: string;
+  platform: string;
+  matched_listener_ids?: string[];
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_followers?: number | null;
+  author_verified?: boolean | null;
+  author_profile_image_url?: string | null;
+  text?: string | null;
+  post_url?: string | null;
+  created_at?: string | null;
+  like_count?: number | null;
+  reply_count?: number | null;
+  repost_count?: number | null;
+  view_count?: number | null;
+  classifier_score?: number | null;
+  engagement_intent?: string | null;
+  resolved_mashup_contact_id?: string | null;
+  status?: string | null;
+}
+export interface PostEngagement {
+  engagement_external_id: string;
+  engagement_type: string;
+  reaction_type?: string | null;
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_url?: string | null;
+  author_headline?: string | null;
+  text?: string | null;
+  created_at?: string | null;
+}
+export interface TopAccount {
+  author_external_id: string;
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_url?: string | null;
+  author_headline?: string | null;
+  platform: string;
+  posts_engaged?: number | null;
+  comments?: number | null;
+  reactions?: number | null;
+  last_engaged_at?: string | null;
+}
+export interface SourceList {
+  audience_id: number;
+  list_title?: string | null;
+  audience_type?: string | null;
+  contact_count?: number | null;
+  is_active?: boolean | null;
+  is_dynamic?: boolean | null;
+  last_synced_at?: string | null;
+  total_listeners_created?: number | null;
+  channel_coverage?: Record<string, number> | null;
+}
+export interface SocialStats {
+  monthly_credit_burn?: number | null;
+  posts_matched?: number | null;
+  posts_reviewed?: number | null;
+  posts_dismissed?: number | null;
+  contacts_resolved?: number | null;
+  x_api_spend_usd?: number | null;
+  listeners_active?: number | null;
+  listeners_paused?: number | null;
+}
+export interface ChannelRule { enabled?: boolean; monthly_credit_cap?: number; per_poll_result_cap?: number; max_comments_per_post?: number; max_reactions_per_post?: number; fetch_engagements?: boolean }
+export interface CaptureRule { enabled?: boolean; min_followers?: number; only_when_classified?: boolean }
+export interface SocialSettings {
+  monthly_credit_cap?: number | null;
+  other_channels_monthly_credit_cap?: number | null;
+  alert_threshold_pct?: number | null;
+  auto_pause_on_cap?: boolean | null;
+  auto_archive_days?: number | null;
+  auto_create_contacts?: boolean | null;
+  classifier_model?: string | null;
+  channel_settings?: Record<string, ChannelRule> | null;
+  contact_capture?: Record<string, CaptureRule> | null;
+}
+export interface XStatus { connected?: boolean; mode?: string | null; x_app_username?: string | null; connected_at?: string | null; degraded_reason?: string | null }
+export interface XMode { auth_mode?: string | null; byo_connected?: boolean | null; shared_available?: boolean | null; shared_cap_total?: number | null; shared_cap_remaining?: number | null }
+export interface SeedJob { job_id?: string; status?: string; stage?: string; error?: string | null; result?: { brand_created?: number; competitors_created?: number; keywords_created?: number; engagement_created?: number; skipped?: string[] } | null }
+export interface CostPreview { posts_per_day_estimate?: number | null; credits_per_month_estimate?: number | null; x_usd_per_month_estimate?: number | null; cached?: boolean; note?: string | null }
+
+/** The rows of an open `{ items: [] }` payload (the dev API surfaces every list as `items`). */
+export function itemsOf<T>(data: unknown): T[] {
+  const d = data as { items?: unknown } | T[] | null | undefined;
+  if (Array.isArray(d)) return d;
+  return Array.isArray(d?.items) ? (d.items as T[]) : [];
+}
+export function totalOf(data: unknown): number | undefined {
+  const t = (data as { total?: unknown } | null | undefined)?.total;
+  return typeof t === "number" ? t : undefined;
+}
+
+export const platformLabel = (p: string | null | undefined): string => PLATFORMS.find((x) => x.value === p)?.label ?? (p ? p : "");
+export const typeLabel = (t: string | null | undefined): string => LISTENER_TYPES.find((x) => x.value === t)?.label ?? (t ? t : "");
+/** A number, or null when the channel did not report one (unknown is not zero). */
+export const num = (n: number | null | undefined): number | null => (typeof n === "number" && Number.isFinite(n) ? n : null);
+export const fmt = (n: number | null | undefined): string => { const v = num(n); return v === null ? "-" : v.toLocaleString(); };
+export const when = (iso: string | null | undefined): string => {
+  if (!iso) return "-";
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? "-" : new Date(t).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+};
+export const cadence = (sec: number | null | undefined): string => {
+  const s = num(sec);
+  if (s === null) return "-";
+  if (s % 3600 === 0) return `every ${s / 3600} h`;
+  if (s % 60 === 0) return `every ${s / 60} min`;
+  return `every ${s} s`;
+};
+/** Credits per month a poll cadence cannot bound: only the cap does, so the cap is what a confirm states. */
+export const capText = (cap: number | null | undefined): string => {
+  const c = num(cap);
+  return c === null ? "no cap reported" : c === 0 ? "no per-listener cap" : `capped at ${c.toLocaleString()} credits a month`;
+};
+export const statusOf = (l: Pick<Listener, "is_active">): "active" | "paused" => (l.is_active ? "active" : "paused");
+
+/**
+ * Only the fields that changed. A cleared text or number is NOT sent: the dev API builds the inner body with
+ * `model_dump(exclude_none=True)`, so a null would be dropped and the save would report something that never happened.
+ */
+export function listenerDiff(before: Listener, next: { name: string; query: string; target_handle: string; poll_interval_sec: number | null; monthly_credit_cap: number | null }): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (next.name.trim() !== before.name) out.name = next.name.trim();
+  if (next.query.trim() && next.query.trim() !== (before.query ?? "")) out.query = next.query.trim();
+  if (next.target_handle.trim() && next.target_handle.trim() !== (before.target_handle ?? "")) out.target_handle = next.target_handle.trim();
+  if (next.poll_interval_sec !== null && next.poll_interval_sec !== num(before.poll_interval_sec)) out.poll_interval_sec = next.poll_interval_sec;
+  if (next.monthly_credit_cap !== null && next.monthly_credit_cap !== num(before.monthly_credit_cap)) out.monthly_credit_cap = next.monthly_credit_cap;
+  return out;
+}
+
+/** A page of a POST-search read: rows plus whether another page follows (from the reported total, else a full page). */
+export function morePages(data: unknown, rows: number, page: number, size: number): boolean {
+  const t = totalOf(data);
+  return t !== undefined ? page * size < t : rows >= size;
+}
+
+/** The sequences a person can enrol into: live ones only. */
+export interface SequenceRow { id: string; name?: string | null; status?: string | null }
+export const isLiveSequence = (s: SequenceRow): boolean => ["live", "waiting", "running", "active"].includes(String(s.status ?? "").toLowerCase());
+
+/** Top-level numeric settings: key, label, max (when the API bounds it). */
+export const SETTING_NUMBERS: { key: "monthly_credit_cap" | "other_channels_monthly_credit_cap" | "alert_threshold_pct" | "auto_archive_days"; label: string; max?: number; hint: string }[] = [
+  { key: "monthly_credit_cap", label: "Monthly credit cap (X)", hint: "The org-wide ceiling on social listening credits." },
+  { key: "other_channels_monthly_credit_cap", label: "Monthly credit cap (other channels)", hint: "LinkedIn, Reddit, Instagram and YouTube together. 0 means no org-wide ceiling." },
+  { key: "alert_threshold_pct", label: "Alert at (% of cap)", max: 100, hint: "You are alerted when spend reaches this share of the cap." },
+  { key: "auto_archive_days", label: "Archive posts after (days)", hint: "Older matched posts are archived." },
+];
+export const CHANNEL_NUMBERS: { key: "monthly_credit_cap" | "per_poll_result_cap" | "max_comments_per_post" | "max_reactions_per_post"; label: string }[] = [
+  { key: "monthly_credit_cap", label: "Monthly credit cap" },
+  { key: "per_poll_result_cap", label: "Posts per poll" },
+  { key: "max_comments_per_post", label: "Comments per post" },
+  { key: "max_reactions_per_post", label: "Reactions per post" },
+];
+
+/** Whole non-negative integer from a text box, or null when empty / invalid. */
+export function wholeNumber(text: string, max?: number): number | null {
+  if (text.trim() === "") return null;
+  const n = Number(text);
+  return Number.isInteger(n) && n >= 0 && (max === undefined || n <= max) ? n : null;
+}

package/blocks/signals/recipes/preview-and-create-a-listener.ts

@@ -0,0 +1,16 @@
+/**
+ * @title Estimate a listener's cost, then create it with a monthly cap
+ * @when Starting to watch a keyword or competitor. Creating a listener makes it poll, and reading posts spends credits, so
+ * a person confirms the cap first. The estimate charges nothing.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function previewThenCreate(query: string, name: string, monthlyCreditCap: number, approved: boolean): Promise<{ estimateCreditsPerMonth: unknown; listenerId?: string }> {
+  const est = await g8.api.signals.previewListenerCost({ body: { listener_type: "keyword", platform: "x", query } });
+  const estimateCreditsPerMonth = (est.data as { credits_per_month_estimate?: unknown }).credits_per_month_estimate;
+  if (!approved) return { estimateCreditsPerMonth };
+  const made = await g8.api.signals.createListener({ body: { listener_type: "keyword", platform: "x", name, query, monthly_credit_cap: monthlyCreditCap } });
+  return { estimateCreditsPerMonth, listenerId: (made.data as { id?: string }).id };
+}

package/blocks/signals/recipes/spend-against-caps.ts

@@ -0,0 +1,14 @@
+/**
+ * @title Compare this month's credit spend with the org-wide cap
+ * @when A budget alert for social listening. A cap of 0 means no org-wide ceiling, which is not "at the limit".
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function spendVsCap(): Promise<{ spent: number | null; cap: number | null; share: number | null }> {
+  const [stats, settings] = await Promise.all([g8.api.signals.getSocialStats({}), g8.api.signals.getSocialSettings({})]);
+  const spent = (stats.data as { monthly_credit_burn?: number }).monthly_credit_burn ?? null;
+  const cap = (settings.data as { monthly_credit_cap?: number }).monthly_credit_cap ?? null;
+  return { spent, cap, share: spent !== null && cap ? spent / cap : null };
+}

package/blocks/signals/recipes/triage-matched-posts.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Read new matched posts and mark them reviewed
+ * @when A daily triage queue for social signals. The read spends nothing (it reads what the worker stored); a post is
+ * identified by its channel AND its id.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function newPosts(limit = 50): Promise<Array<{ platform: string; id: string; text: string | null }>> {
+  const res = await g8.api.signals.searchMatchedPosts({ body: { status: "new", limit, page: 1 } });
+  const rows = ((res.data as { items?: Array<{ platform: string; post_external_id: string; text?: string | null }> }).items ?? []);
+  return rows.map((p) => ({ platform: p.platform, id: p.post_external_id, text: p.text ?? null }));
+}
+
+export async function markReviewed(platform: "x" | "linkedin" | "reddit" | "instagram" | "youtube", postId: string): Promise<void> {
+  await g8.api.signals.markPost({ path: { post_id: postId }, query: { platform }, body: { status: "reviewed" } });
+}

package/blocks/visitors/components/traffic-chart.tsx

@@ -75,7 +75,8 @@ export function LineChart({ points, metric }: { points: TrendPoint[]; metric: Me
 
 function activeNow(envelope: unknown): number | undefined {
   const data = (envelope as { data?: Record<string, unknown> } | null)?.data;
-  const value = data?.active_users_5min ?? data?.active_5min ?? data?.active_users ?? data?.five_min ?? data?.active_now;
+  // The realtime report answers `active_5m` (reports/analytics/queries/realtime.py); the older names stay as fallbacks.
+  const value = data?.active_5m ?? data?.active_users_5min ?? data?.active_5min ?? data?.active_users ?? data?.five_min ?? data?.active_now;
   return typeof value === "number" ? value : undefined;
 }
 
@@ -114,7 +115,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
           ))}
         </div>
         <p className="text-sm text-muted-foreground" aria-live="polite">
-          {now != null ? `${now} on the site now` : ""}
+          {now != null ? `${now} on the site now` : live.data || live.error ? "On the site now: -" : ""}
         </p>
       </div>
 

package/blocks/web-analytics/README.md

@@ -0,0 +1,102 @@
+# web-analytics
+
+Website analytics for your own sites: **traffic, acquisition, audience, pages, engagement, conversions and realtime**, read from the
+tracking pipeline (the same reports as the graph8 Analytics pages). Every call is a free read. Nothing here is billable, external
+or destructive, so there are no confirmations.
+
+## Screens
+
+`WebAnalyticsScreen` (`components/web-analytics-screen.tsx`) is the finished page.
+
+```tsx
+import { WebAnalyticsScreen } from "@/g8/web-analytics/components/web-analytics-screen";
+export default function Page() { return <WebAnalyticsScreen />; }
+```
+
+One **site picker** and one **window** drive every tab and live in the URL, so a link opens the same view:
+`?site=pubKeyA,pubKeyB` (none = all sites), `?days=7|30|90|365` or `?from=YYYY-MM-DD&to=YYYY-MM-DD`, `?bots=1`, `?internal=1`, `?tab=`.
+
+| Tab | What it shows |
+|---|---|
+| Overview | visitors, new visitors, sessions, page views; daily traffic; conversion rate; top pages (a row opens the page detail) |
+| Acquisition | channels, channel trend, sources and mediums, UTM campaigns, referrals, social networks, search engines |
+| Audience | top countries, cities and languages; every country or city; languages; browsers, operating systems, devices; new or returning |
+| Pages | top, landing and exit pages; custom events; a page detail panel (`?page=/path`) with views, visitors, form submissions, bookings |
+| Engagement | sessions, pages per session, time on site, bounce and engaged share against the previous period; trend; depth and time distributions; by channel, campaign, landing page |
+| Conversions | conversion rate; funnel (visitors, viewed a form, submitted, booked); goals and their trend; forms, form trend, form analysis |
+| Realtime | active visitors in the last 5 and 30 minutes, active pages, traffic sources, locations; re-read every 10 seconds while visible |
+
+Optional props: `resolveLandingPage(path)` returns the id of the landing page at exactly that address (one match only), and `onOpenLandingPage(id)` opens it
+(the hubspot stack wires both to the pages block). `refreshSeconds` (default 10; 0 turns the realtime poll off), `toolbarActions`, `className`.
+
+## Rules the screen keeps
+
+- **Loading is visible.** Changing a site, the window or a switch dims every card (and a first load shows a skeleton). A failed or refused request clears the card and shows the error with Retry; the previous numbers never stay under an error.
+- **Unavailable is not zero.** The reports swallow a failed ClickHouse query and answer `meta.stale: true` with empty data. A card in that state says it is unavailable (with Retry), and the tiles that belong to that card go with it.
+- **Unknown rates are dashes.** A conversion rate the API sends as null (no visitors, no viewers) and any rate whose denominator is 0 shows a dash, never zero percent.
+- **No request the API refuses.** `days` 1 to 365; a custom range needs both days, real dates, start not after end, at most 365 days (Apply is disabled with the reason otherwise); site keys are letters, digits, `-`, `_`; `limit` never exceeds each report's maximum (languages 100, form analysis 100, engagement by landing page 100, realtime pages and sources 50, the rest 200); a page path must start with `/` and use plain URL characters.
+- **Sort, then cut.** Tables sort the whole list a read returned and only then show the first 10 ("Show all N"). A read that came back full says "Showing the first N".
+- **No invented defaults.** The window defaults to the API's own 30 days; bots and internal traffic stay excluded (the flags are sent only when switched on).
+
+## Types
+
+The contract answers every web analytics report with `AnalyticsResponse { success, data: object | array, meta }`: `data` is **untyped**. The row types in
+`lib/web-analytics-types.ts` are typed from the backend instead (the column aliases of `reports/analytics/queries/{audience,acquisition,behavior,conversions,engagement,realtime}.py`).
+Every field is optional and read defensively.
+
+## Install
+
+```
+npx @graph8/sdk add web-analytics
+```
+
+Installs `foundation`, `crm` and `visitors` first if missing. Everything lands under `g8/web-analytics/`. Your app's proxy must allow the `analytics` and `streams` prefixes.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| The website | The graph8 tracking snippet is pasted into the site. Without it every report is empty. | The visitors block's SnippetInstall reports events received. |
+| graph8 key | `analytics:read`, and `integrations:read` for the site list | `g8.api.me.describeCurrentKey()` |
+
+## Operations (39)
+
+- `get_acquisition_campaigns_analytics_acquisition_campaigns_get`
+- `get_acquisition_channels_analytics_acquisition_channels_get`
+- `get_acquisition_channels_trend_analytics_acquisition_channels_trend_get`
+- `get_acquisition_referrals_analytics_acquisition_referrals_get`
+- `get_acquisition_search_analytics_acquisition_search_get`
+- `get_acquisition_social_analytics_acquisition_social_get`
+- `get_acquisition_sources_analytics_acquisition_sources_get`
+- `get_audience_behavior_analytics_audience_behavior_get`
+- `get_audience_demographics_analytics_audience_demographics_get`
+- `get_audience_languages_analytics_audience_languages_get`
+- `get_audience_overview_analytics_audience_overview_get`
+- `get_audience_trend_analytics_audience_trend_get`
+- `get_conversion_rate_analytics_conversions_rate_get`
+- `get_engagement_by_campaign_analytics_engagement_by_campaign_get`
+- `get_engagement_by_channel_analytics_engagement_by_channel_get`
+- `get_engagement_by_landing_page_analytics_engagement_by_landing_page_get`
+- `get_engagement_overview_analytics_engagement_overview_get`
+- `get_engagement_trend_analytics_engagement_trend_get`
+- `get_events_analytics_behavior_events_get`
+- `get_exit_pages_analytics_behavior_exit_pages_get`
+- `get_form_analysis_analytics_conversions_forms_analysis_get`
+- `get_forms_analytics_conversions_forms_get`
+- `get_forms_trend_analytics_conversions_forms_trend_get`
+- `get_funnel_analytics_conversions_funnel_get`
+- `get_geo_cities_analytics_audience_geo_cities_get`
+- `get_geo_countries_analytics_audience_geo_get`
+- `get_goals_analytics_conversions_goals_get`
+- `get_goals_trend_analytics_conversions_goals_trend_get`
+- `get_landing_pages_analytics_behavior_landing_pages_get`
+- `get_page_metrics_analytics_behavior_page_metrics_get`
+- `get_realtime_analytics_realtime_get`
+- `get_realtime_locations_analytics_realtime_locations_get`
+- `get_realtime_pages_analytics_realtime_pages_get`
+- `get_realtime_sources_analytics_realtime_sources_get`
+- `get_session_depth_distribution_analytics_engagement_depth_distribution_get`
+- `get_technology_overview_analytics_audience_technology_get`
+- `get_time_on_site_distribution_analytics_engagement_time_distribution_get`
+- `get_top_pages_analytics_behavior_pages_get`
+- `list_org_streams_streams_get`