@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/brandKit.d.ts

@@ -0,0 +1,686 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.brandKit` (Brand Kit): 30 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_custom_layout_template_brand_kit_layout_templates_custom_post">;
+ *
+ * Reference with examples: brandKit.md
+ */
+/* eslint-disable */
+
+/** `g8.api.brandKit.<member>` -> the operationId it calls. */
+export interface BrandKitMembers {
+  createCustomLayoutTemplate: "create_custom_layout_template_brand_kit_layout_templates_custom_post";
+  deleteBrandKitTemplates: "delete_brand_kit_templates_brand_kit_templates_delete";
+  getBrandKitHomepage: "get_brand_kit_homepage_brand_kit_homepage_get";
+  getBrandKitOverview: "get_brand_kit_overview_brand_kit_get";
+  getBrandKitTemplates: "get_brand_kit_templates_brand_kit_templates_get";
+  getHomepageSections: "get_homepage_sections_brand_kit_sections_get";
+  getLayoutSelections: "get_layout_selections_brand_kit_layout_selections_get";
+  getLayoutTemplatesStatus: "get_layout_templates_status_brand_kit_layout_templates_status_get";
+  getNewsletterSelections: "get_newsletter_selections_brand_kit_newsletter_selections_get";
+  getNewsletterTemplatesStatus: "get_newsletter_templates_status_brand_kit_newsletter_templates_status_get";
+  getSectionLibrary: "get_section_library_brand_kit_section_library_get";
+  getSectionLibraryItem: "get_section_library_item_brand_kit_section_library__section_id__get";
+  getSectionTagOverrides: "get_section_tag_overrides_brand_kit_section_tag_overrides_get";
+  getTemplateGenerationStatus: "get_template_generation_status_brand_kit_templates_status_get";
+  improveCustomTemplateIdea: "improve_custom_template_idea_brand_kit_layout_templates_improve_idea_post";
+  listArchetypes: "list_archetypes_brand_kit_archetypes_get";
+  listCandidatePagesForSectionLibrary: "list_candidate_pages_for_section_library_brand_kit_section_library_candidate_pages_get";
+  listCustomLayoutTemplates: "list_custom_layout_templates_brand_kit_layout_templates_custom_get";
+  listNewsletterArchetypes: "list_newsletter_archetypes_brand_kit_newsletter_archetypes_get";
+  listNewsletterTemplates: "list_newsletter_templates_brand_kit_newsletter_templates_get";
+  planCustomTemplate: "plan_custom_template_brand_kit_layout_templates_custom_plan_post";
+  rebuildSectionLibrary: "rebuild_section_library_brand_kit_section_library_rebuild_post";
+  recaptureHomepageHtml: "recapture_homepage_html_brand_kit_homepage_recapture_post";
+  regenerateCustomLayoutTemplate: "regenerate_custom_layout_template_brand_kit_layout_templates_custom__landing_page_id__regenerate_post";
+  regenerateLayoutTemplates: "regenerate_layout_templates_brand_kit_layout_templates_regenerate_post";
+  regenerateNewsletterTemplates: "regenerate_newsletter_templates_brand_kit_newsletter_templates_regenerate_post";
+  saveLayoutSelections: "save_layout_selections_brand_kit_layout_selections_put";
+  saveNewsletterSelections: "save_newsletter_selections_brand_kit_newsletter_selections_put";
+  saveSectionTagOverrides: "save_section_tag_overrides_brand_kit_section_tag_overrides_put";
+  triggerBrandExtraction: "trigger_brand_extraction_brand_kit_extract_post";
+}
+
+/** Input and output of every `g8.api.brandKit` operation, keyed by operationId. */
+export interface BrandKitOperations {
+  /**
+   * POST /brand-kit/layout-templates/custom
+   * Create Custom Layout Template
+   * tier: write · scope: campaigns:write
+   */
+  create_custom_layout_template_brand_kit_layout_templates_custom_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CustomLayoutTemplateRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * DELETE /brand-kit/templates
+   * Delete Brand Kit Templates
+   * tier: destructive · scope: campaigns:delete
+   */
+  delete_brand_kit_templates_brand_kit_templates_delete: {
+    input: {
+    query?: {
+      /** `layout_archetype` for templates built from a chosen archetype, `homepage` for the one cloned from the org's own site. Omit for both. */
+      source?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/homepage
+   * Get Brand Kit Homepage
+   * tier: read · scope: campaigns:read
+   */
+  get_brand_kit_homepage_brand_kit_homepage_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit
+   * Get Brand Kit Overview
+   * tier: read · scope: campaigns:read
+   */
+  get_brand_kit_overview_brand_kit_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/templates
+   * Get Brand Kit Templates
+   * tier: read · scope: campaigns:read
+   */
+  get_brand_kit_templates_brand_kit_templates_get: {
+    input: {
+    query?: {
+      /** `layout_archetype` for templates built from a chosen archetype, `homepage` for the one cloned from the org's own site. Omit for both. */
+      source?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/sections
+   * Get Homepage Sections
+   * tier: read · scope: campaigns:read
+   */
+  get_homepage_sections_brand_kit_sections_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/layout-selections
+   * Get Layout Selections
+   * tier: read · scope: campaigns:read
+   */
+  get_layout_selections_brand_kit_layout_selections_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/layout-templates/status
+   * Get Layout Templates Status
+   * tier: read · scope: campaigns:read
+   */
+  get_layout_templates_status_brand_kit_layout_templates_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/newsletter-selections
+   * Get Newsletter Selections
+   * tier: read · scope: campaigns:read
+   */
+  get_newsletter_selections_brand_kit_newsletter_selections_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/newsletter-templates/status
+   * Get Newsletter Templates Status
+   * tier: read · scope: campaigns:read
+   */
+  get_newsletter_templates_status_brand_kit_newsletter_templates_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/section-library
+   * Get Section Library
+   * tier: read · scope: campaigns:read
+   */
+  get_section_library_brand_kit_section_library_get: {
+    input: {
+    query?: {
+      /** Include each section's full HTML and CSS. Off by default because the response is an order of magnitude larger with it on - use the detail route for a single preview, and this only for a bulk export. */
+      include_code?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/section-library/{section_id}
+   * Get Section Library Item
+   * tier: read · scope: campaigns:read
+   */
+  get_section_library_item_brand_kit_section_library__section_id__get: {
+    input: {
+    path: {
+      /** Section id. */
+      section_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/section-tag-overrides
+   * Get Section Tag Overrides
+   * tier: read · scope: campaigns:read
+   */
+  get_section_tag_overrides_brand_kit_section_tag_overrides_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/templates/status
+   * Get Template Generation Status
+   * tier: read · scope: campaigns:read
+   */
+  get_template_generation_status_brand_kit_templates_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/layout-templates/improve-idea
+   * Improve Custom Template Idea
+   * tier: write · scope: campaigns:write
+   */
+  improve_custom_template_idea_brand_kit_layout_templates_improve_idea_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ImproveIdeaRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * GET /brand-kit/archetypes
+   * List Archetypes
+   * tier: read · scope: campaigns:read
+   */
+  list_archetypes_brand_kit_archetypes_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/section-library/candidate-pages
+   * List Candidate Pages For Section Library
+   * tier: read · scope: campaigns:read
+   */
+  list_candidate_pages_for_section_library_brand_kit_section_library_candidate_pages_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/layout-templates/custom
+   * List Custom Layout Templates
+   * tier: read · scope: campaigns:read
+   */
+  list_custom_layout_templates_brand_kit_layout_templates_custom_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/newsletter-archetypes
+   * List Newsletter Archetypes
+   * tier: read · scope: campaigns:read
+   */
+  list_newsletter_archetypes_brand_kit_newsletter_archetypes_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * GET /brand-kit/newsletter-templates
+   * List Newsletter Templates
+   * tier: read · scope: campaigns:read
+   */
+  list_newsletter_templates_brand_kit_newsletter_templates_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioListPayload_;
+  };
+  /**
+   * POST /brand-kit/layout-templates/custom/plan
+   * Plan Custom Template
+   * tier: write · scope: campaigns:write
+   */
+  plan_custom_template_brand_kit_layout_templates_custom_plan_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CustomTemplatePlanRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/section-library/rebuild
+   * Rebuild Section Library
+   * tier: write · scope: campaigns:write
+   */
+  rebuild_section_library_brand_kit_section_library_rebuild_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: SectionLibraryRebuildRequest | null;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/homepage/recapture
+   * Recapture Homepage Html
+   * tier: write · scope: campaigns:write
+   */
+  recapture_homepage_html_brand_kit_homepage_recapture_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/layout-templates/custom/{landing_page_id}/regenerate
+   * Regenerate Custom Layout Template
+   * tier: write · scope: campaigns:write
+   */
+  regenerate_custom_layout_template_brand_kit_layout_templates_custom__landing_page_id__regenerate_post: {
+    input: {
+    path: {
+      /** The custom template to rebuild. */
+      landing_page_id: string;
+    };
+    query?: {
+      /** Discard the stored plan and re-derive one from the original idea. Leave false to rebuild against the plan that was approved. */
+      clear_plan?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/layout-templates/regenerate
+   * Regenerate Layout Templates
+   * tier: write · scope: campaigns:write
+   */
+  regenerate_layout_templates_brand_kit_layout_templates_regenerate_post: {
+    input: {
+    query?: {
+      /** Rebuild ONE archetype's template. Omit to run the layout picker and rebuild every selected archetype - which is much more work. */
+      archetype_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/newsletter-templates/regenerate
+   * Regenerate Newsletter Templates
+   * tier: write · scope: campaigns:write
+   */
+  regenerate_newsletter_templates_brand_kit_newsletter_templates_regenerate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * PUT /brand-kit/layout-selections
+   * Save Layout Selections
+   * tier: write · scope: campaigns:write
+   */
+  save_layout_selections_brand_kit_layout_selections_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LayoutSelectionRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * PUT /brand-kit/newsletter-selections
+   * Save Newsletter Selections
+   * tier: write · scope: campaigns:write
+   */
+  save_newsletter_selections_brand_kit_newsletter_selections_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: NewsletterSelectionsRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * PUT /brand-kit/section-tag-overrides
+   * Save Section Tag Overrides
+   * tier: write · scope: campaigns:write
+   */
+  save_section_tag_overrides_brand_kit_section_tag_overrides_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SectionTagOverridesRequest;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+  /**
+   * POST /brand-kit/extract
+   * Trigger Brand Extraction
+   * tier: write · scope: campaigns:write
+   */
+  trigger_brand_extraction_brand_kit_extract_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: BrandExtractionRequest | null;
+  };
+    output: ApiResponse_StudioPayload_;
+  };
+}
+
+// 18 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_StudioListPayload_ {
+  data: StudioListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_StudioPayload_ {
+  data: StudioPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.AttachedAsset`.
+ *
+ * An asset the generated page MUST use. Capped by the app at 5 images and 2
+ * videos per submission; the cap is a model validator there, so it answers
+ * 422 through the same path as any other body error.
+ */
+export interface AttachedAsset {
+  /** Alt text. */
+  alt_text?: string | null;
+  /** Asset id. */
+  id: string;
+  /** Where the asset should land on the page. */
+  position_hint?: "hero" | "body" | "any";
+  /** Poster frame for a video. */
+  poster_url?: string | null;
+  /** Title. */
+  title?: string | null;
+  /** Asset kind. */
+  type: "image" | "video";
+  /** Public URL the generated page will reference. */
+  url: string;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.TriggerExtractionPayload`.
+ *
+ * `website_url` omitted re-runs extraction against the website already on the
+ * org's company profile. Supplying one EXTRACTS A DIFFERENT SITE, which
+ * replaces the org's design tokens and homepage capture.
+ */
+export interface BrandExtractionRequest {
+  /** Site to extract from. Omit to re-extract the org's current website. */
+  website_url?: string | null;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.CustomLayoutTemplateRequest`.
+ *
+ * `plan` is the object `POST /brand-kit/layout-templates/custom/plan` returns.
+ * Passing it back is how you build the page you previewed rather than a new
+ * interpretation of the same idea.
+ */
+export interface CustomLayoutTemplateRequest {
+  /** Images and videos the page must use. Max 5 images and 2 videos. */
+  attached_assets?: Array<AttachedAsset>;
+  /** Plain-language description of the page to build. */
+  idea: string;
+  /** Short title. Derived from the idea when omitted. */
+  name?: string | null;
+  /** An approved plan from the plan-preview step. */
+  plan?: LpPlan | null;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.CustomPlanRequest`.
+ *
+ * The preview half of the pair above. Builds nothing and stores nothing.
+ */
+export interface CustomTemplatePlanRequest {
+  /** Images and videos the plan must place. */
+  attached_assets?: Array<AttachedAsset>;
+  /** Plain-language description of the page to plan. */
+  idea: string;
+  /** Short title. */
+  name?: string | null;
+}
+
+/** Mirrors `campaign_builder.routers.brand_kit.ImproveIdeaRequest`. */
+export interface ImproveIdeaRequest {
+  /** The raw idea to rewrite into a fuller brief. */
+  idea: string;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.LayoutSelectionRequest`.
+ *
+ * REPLACES the org's selection. Ids come from `GET /brand-kit/archetypes`.
+ */
+export interface LayoutSelectionRequest {
+  /** The complete set of selected layout archetype ids. */
+  archetype_ids: Array<string>;
+}
+
+/** Full landing-page plan — 1..8 sections. */
+export interface LpPlan {
+  sections: Array<PlanSection>;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.NewsletterSelectionsBody`.
+ *
+ * REPLACES the org's selection. Ids come from `GET /brand-kit/newsletter-archetypes`.
+ */
+export interface NewsletterSelectionsRequest {
+  /** The complete set of selected newsletter archetype ids. */
+  archetype_ids: Array<string>;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * One media slot inside a plan section.
+ *
+ * ``locked=True`` marks items the user explicitly attached (no swap
+ * affordance in the UI). AI-picked items default to ``locked=False``
+ * and can be swapped before approval.
+ */
+export interface PlanMediaEntry {
+  asset_id?: string | null;
+  asset_type: "image" | "video";
+  asset_url?: string | null;
+  context: string;
+  locked?: boolean;
+  position_hint?: "hero" | "body" | "any";
+  role: string;
+}
+
+/** One section of the landing-page plan. */
+export interface PlanSection {
+  media?: Array<PlanMediaEntry>;
+  name: string;
+  purpose: string;
+}
+
+/**
+ * Mirrors `RebuildSectionLibraryRequest`.
+ *
+ * The two lists are NOT interchangeable: `page_urls` REPLACES the automatic
+ * page selection, `extra_page_urls` ADDS to it. Sending the first is how you
+ * override the picker; sending the second is how you top it up.
+ */
+export interface SectionLibraryRebuildRequest {
+  /** Add these pages to whatever the picker chose. */
+  extra_page_urls?: Array<string> | null;
+  /** Replace the automatic page selection with exactly these pages. */
+  page_urls?: Array<string> | null;
+}
+
+/** Mirrors `campaign_builder.routers.brand_kit.SectionTagOverride`. */
+export interface SectionTagOverride {
+  /** Category override for this section. */
+  category?: string | null;
+  /** Tags added to this section. */
+  custom?: Array<string>;
+  /** Auto-derived tags suppressed for this section. */
+  hidden?: Array<string>;
+}
+
+/**
+ * Mirrors `campaign_builder.routers.brand_kit.SectionTagOverridesRequest`.
+ *
+ * Durable and UPSERTED by section id - sections you do not mention keep the
+ * overrides they already had.
+ */
+export interface SectionTagOverridesRequest {
+  /** Section id -> tag override. */
+  overrides?: Record<string, SectionTagOverride>;
+}
+
+/**
+ * An open envelope for a LIST result, so a bare list keeps its shape.
+ *
+ * A handler that returns `[...]` and one that returns `{"documents": [...]}`
+ * both land on `items`, and the named key is preserved beside it so a caller
+ * reading the app's own spelling is not broken by the normalisation.
+ */
+export interface StudioListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one settings block, document or brand artefact.
+ *
+ * OPEN on purpose. These surfaces are configuration and generated content,
+ * and both grow: a new toggle on a settings block or a new field on a
+ * generated document must reach a caller on the day it ships, not on the day
+ * somebody remembers to widen a mirror. A closed response model here would
+ * silently DROP the new key, which reads to the caller as "the product does
+ * not have that setting".
+ *
+ * The request side is the opposite and is mirrored exactly - see the module
+ * docstring for why the asymmetry is deliberate.
+ */
+export type StudioPayload = Record<string, unknown>;