Typy položek

Položky v BriefGate mají typ. Agent řekne, co potřebuje; klientský portál vstup kontroluje v reálném čase; get_intake_results vrátí data, která agent rovnou použije, bez dalšího parsování a převodů typů.

Každá definice položky potřebuje minimálně key (jedinečný v rámci intake), label (vidí ho klient) a type. Většina typů přijímá nepovinná constraints, která portál vynutí ještě před odesláním.

text

Jednořádkové textové pole. Hodí se na krátké strukturované řetězce, jako jsou měřicí ID, názvy účtů nebo kódy.

Omezení (uvnitř objektu constraints)

Pole	Typ	Popis
`min_chars`	integer	Nejmenší počet znaků.
`max_chars`	integer	Největší počet znaků.

Pole přímo na položce

Pole	Typ	Popis
`pattern`	string	Regulární výraz ECMAScript, kterému hodnota musí odpovídat. Patří přímo do definice položky, ne do `constraints`.

Příklad — měřicí ID Google Analytics

json

{
  "key": "ga4_id",
  "label": "Google Analytics 4 Measurement ID",
  "help": "Found in GA4 > Admin > Data Streams. Format: G-XXXXXXXXXX",
  "type": "text",
  "required": true,
  "pattern": "^G-[A-Z0-9]+"
}

Co vrátí get_intake_results

json

"ga4_id": "G-K4M9X3R2B1"

longtext

Víceřádkové pole na několik odstavců. Hodí se na delší texty, medailonky, poslání firmy a všude, kde klient potřebuje prostor.

Omezení

Pole	Typ	Popis
`min_chars`	integer	Nejmenší počet znaků.
`max_chars`	integer	Největší počet znaků.

Příklad — text do hlavičky

json

{
  "key": "hero_copy",
  "label": "Homepage hero text",
  "help": "A short paragraph (up to 400 characters) that captures the spirit of the restaurant. Appears above the fold.",
  "type": "longtext",
  "required": true,
  "constraints": {
    "max_chars": 400
  }
}

Co vrátí get_intake_results

json

"hero_copy": "Since 1987, handcrafted Neapolitan pizza in the heart of the city. Come hungry, leave happy."

file

Nahrání jednoho souboru. Hodí se na dokumenty, PDF, tabulky, fonty a další binární soubory, které nejsou obrázky.

Omezení

Pole	Typ	Popis
`formats`	string[]	Povolené přípony bez tečky, například `["pdf","docx"]`. Nerozlišuje velikost písmen.
`max_bytes`	integer	Největší velikost souboru v bajtech. Výchozí je 52 428 800 (50 MB).

Příklad — podepsaná smlouva

json

{
  "key": "signed_contract",
  "label": "Signed project contract",
  "help": "Upload the signed PDF you received by email.",
  "type": "file",
  "required": true,
  "constraints": {
    "formats": ["pdf"],
    "max_bytes": 10485760
  }
}

Co vrátí get_intake_results

json

"signed_contract": {
  "filename": "bella-napoli-contract-signed.pdf",
  "url": "https://files.briefgate.dev/in_8f3kQmR2/signed_contract.pdf?token=sig_abc&expires=1710615600",
  "mime": "application/pdf",
  "size": 283492,
  "checksum_sha256": "a3f2e1..."
}

url je podepsaná adresa s platností 24 hodin. Stáhněte soubor včas, nebo si zavolejte get_intake_results znovu a dostanete čerstvou adresu.

file_list

Skupina více nahraných souborů. Hodí se na fotogalerie, balíčky podkladů a všude, kde potřebujete několik souborů stejné kategorie.

Omezení

Pole	Typ	Popis
`formats`	string[]	Povolené přípony souborů.
`max_bytes`	integer	Největší velikost jednoho souboru.
`min_count`	integer	Nejmenší požadovaný počet souborů.
`max_count`	integer	Největší přijímaný počet souborů.

Příklad — fotky restaurace

json

{
  "key": "photos",
  "label": "Food and interior photos",
  "help": "Upload between 5 and 15 photos of your food, interior, and ambience.",
  "type": "file_list",
  "required": true,
  "constraints": {
    "formats": ["jpg", "png", "heic"],
    "min_count": 5,
    "max_count": 15
  }
}

Co vrátí get_intake_results

json

"photos": [
  {
    "filename": "interior-01.jpg",
    "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/interior-01.jpg?token=...",
    "mime": "image/jpeg",
    "size": 3204812,
    "checksum_sha256": "b4c1d2..."
  },
  {
    "filename": "pizza-margherita.jpg",
    "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/pizza-margherita.jpg?token=...",
    "mime": "image/jpeg",
    "size": 2917034,
    "checksum_sha256": "f9e3a1..."
  }
]

image

Nahrání obrázku s volitelnými omezeními na rozměry a formát. Použijte místo file, když potřebujete vynutit rozlišení nebo průhlednost.

Omezení

Pole	Typ	Popis
`formats`	string[]	Výchozí: `["svg","png","jpg","jpeg","webp"]`.
`min_width`	integer	Nejmenší šířka obrázku v pixelech.
`max_width`	integer	Největší šířka obrázku v pixelech.
`min_height`	integer	Nejmenší výška obrázku v pixelech.
`max_height`	integer	Největší výška obrázku v pixelech.
`max_bytes`	integer	Největší velikost souboru v bajtech.
`transparent_background`	boolean	S `true` portál klienta upozorní, když obrázek nemá alfa kanál.

Příklad — logo

json

{
  "key": "logo",
  "label": "Company logo",
  "help": "SVG or PNG with a transparent background. Minimum 512px on the shortest side.",
  "type": "image",
  "required": true,
  "constraints": {
    "formats": ["svg", "png"],
    "min_width": 512,
    "transparent_background": true
  }
}

Co vrátí get_intake_results

json

"logo": {
  "filename": "logo-transparent.png",
  "url": "https://files.briefgate.dev/in_8f3kQmR2/logo-transparent.png?token=...",
  "mime": "image/png",
  "width": 1024,
  "height": 512,
  "size": 48210
}

color_list

Výběr jedné nebo více barev v hexadecimálním zápisu. Portál nabízí vizuální výběr barvy i zadání hexu. Omezení tu nejsou potřeba — portál vždy ověří, že jde o platný hex kód.

Příklad — firemní paleta

json

{
  "key": "brand_colors",
  "label": "Brand colors",
  "help": "Select your primary and secondary brand colors. Add as many as you use.",
  "type": "color_list",
  "required": true
}

Co vrátí get_intake_results

json

"brand_colors": ["#1B2A4A", "#E8E2D9", "#C8382E"]

select

Rozbalovací seznam nebo přepínače, kde klient vybere právě jednu možnost ze seznamu, který zadáte. Hodí se, když potřebujete omezenou sadu hodnot.

Povinná pole

Pole	Typ	Popis
`options`	array	Pole objektů `{value, label}`. `value` se uloží, `label` vidí klient.

Příklad — platforma webu

json

{
  "key": "platform",
  "label": "Preferred website platform",
  "type": "select",
  "required": true,
  "options": [
    { "value": "wordpress", "label": "WordPress" },
    { "value": "webflow",   "label": "Webflow" },
    { "value": "shopify",   "label": "Shopify" },
    { "value": "custom",    "label": "Custom / I'm not sure" }
  ]
}

Co vrátí get_intake_results

json

"platform": "wordpress"

Výsledkem je vždy řetězec z value, nikdy label.

boolean

Přepínač ano/ne. Portál ho podle motivu vykreslí jako dvojici jasně popsaných tlačítek nebo jako zaškrtávátko.

Příklad — dotaz na stávající web

json

{
  "key": "has_existing_site",
  "label": "Do you have an existing website?",
  "type": "boolean",
  "required": true
}

Co vrátí get_intake_results

json

"has_existing_site": true

url

Pole pro adresu s vestavěnou kontrolou http/https. Volitelně ho omezíte na konkrétní doménu nebo tvar cesty.

Pole přímo na položce

Pole	Typ	Popis
`pattern`	string	Regulární výraz ECMAScript, kterému adresa musí odpovídat. Patří přímo do definice položky, ne do `constraints`. Použijte pro omezení na konkrétní doménu.

Příklad — adresa stávajícího webu

json

{
  "key": "existing_site_url",
  "label": "Existing website address",
  "help": "The full URL including https://",
  "type": "url",
  "required": false
}

Co vrátí get_intake_results

json

"existing_site_url": "https://old.bellanapoli.com"

secret

Pole pro šifrovaný přístupový údaj. Portál zobrazí pole jako u hesla, s ikonou zámku a jasnou informací, že se hodnota ukládá bezpečně. Otevřený text se zašifruje přes libsodium sealed box ještě před odesláním z prohlížeče a nikdy se neloguje, neindexuje ani neposílá ve webhoocích.

Přístupy propadají po 30 dnech a odhalit je lze právě jednou. Po odhalení token okamžitě propadá.

Příklad — přihlášení do administrace CMS

json

{
  "key": "cms_credentials",
  "label": "WordPress admin credentials",
  "help": "Your current admin username and password. Stored encrypted and only accessible to your project team.",
  "type": "secret",
  "required": false
}

Co vrátí get_intake_results

Při prvním volání se dešifrovaný text vrátí přímo:

json

"cms_credentials": {
  "value": "username:password",
  "one_time": true,
  "first_reveal": true,
  "expires_at": "2024-04-15T10:22:00Z"
}

Při všech dalších voláních value chybí (first_reveal: false). Uložte si text dřív, než budete pokračovat — podruhé ho nedostanete. Přístupy propadají po 30 dnech.

Vyžaduje scope secrets:read nebo admin na API klíči.

structured

Hodnota v JSON odpovídající schématu JSON Schema, které zadáte. Portál ze schématu vygeneruje formulář (u jednoduchých plochých schémat) nebo nabídne editor JSON (u složitých a vnořených). Odeslaná hodnota se proti schématu ověří na serveru dřív, než se položka přijme.

Povinná pole

Pole	Typ	Popis
`schema`	object	Platný objekt JSON Schema (draft 7 nebo 2020-12).

Příklad — otevírací doba

json

{
  "key": "opening_hours",
  "label": "Opening hours",
  "help": "Your regular weekly schedule. Use a simple time range like '12:00-22:00' or the word 'Closed'.",
  "type": "structured",
  "required": true,
  "schema": {
    "type": "object",
    "required": ["mon_fri", "sat", "sun"],
    "properties": {
      "mon_fri": { "type": "string", "title": "Monday to Friday", "example": "12:00-22:00" },
      "sat":     { "type": "string", "title": "Saturday",          "example": "12:00-23:00" },
      "sun":     { "type": "string", "title": "Sunday",            "example": "Closed" }
    }
  }
}

Co vrátí get_intake_results

json

"opening_hours": {
  "mon_fri": "12:00-22:00",
  "sat": "12:00-23:00",
  "sun": "13:00-21:00"
}

Vrácený objekt zaručeně odpovídá zadanému schématu.

Typy dohromady: příklad webu restaurace

Následující pole items pokrývá hlavní typy položek na realistickém projektu:

json

[
  {
    "key": "logo",
    "label": "Restaurant logo",
    "type": "image",
    "required": true,
    "constraints": { "formats": ["svg","png"], "min_width": 512, "transparent_background": true }
  },
  {
    "key": "brand_colors",
    "label": "Brand colors",
    "type": "color_list",
    "required": true
  },
  {
    "key": "hero_copy",
    "label": "Hero section tagline",
    "type": "longtext",
    "required": true,
    "constraints": { "max_chars": 400 }
  },
  {
    "key": "ga4_id",
    "label": "Google Analytics 4 ID",
    "type": "text",
    "required": false,
    "pattern": "^G-[A-Z0-9]+"
  },
  {
    "key": "has_existing_site",
    "label": "Do you have an existing website?",
    "type": "boolean",
    "required": true
  },
  {
    "key": "existing_site_url",
    "label": "Existing website URL",
    "type": "url",
    "required": false
  },
  {
    "key": "platform",
    "label": "Preferred platform",
    "type": "select",
    "required": true,
    "options": [
      { "value": "wordpress", "label": "WordPress" },
      { "value": "webflow", "label": "Webflow" },
      { "value": "custom", "label": "Custom / I'm not sure" }
    ]
  },
  {
    "key": "cms_credentials",
    "label": "Existing CMS credentials",
    "type": "secret",
    "required": false
  },
  {
    "key": "menu_pdf",
    "label": "Menu (PDF)",
    "type": "file",
    "required": true,
    "constraints": { "formats": ["pdf"], "max_bytes": 10485760 }
  },
  {
    "key": "photos",
    "label": "Food and interior photos",
    "type": "file_list",
    "required": true,
    "constraints": { "formats": ["jpg","png","heic"], "min_count": 5, "max_count": 15 }
  },
  {
    "key": "opening_hours",
    "label": "Opening hours",
    "type": "structured",
    "required": true,
    "schema": {
      "type": "object",
      "required": ["mon_fri","sat","sun"],
      "properties": {
        "mon_fri": { "type": "string" },
        "sat":     { "type": "string" },
        "sun":     { "type": "string" }
      }
    }
  }
]

Kontrola vstupů

Kontrola běží na serveru a probíhá při nahrání, ještě než se položka označí jako submitted. Když soubor nesplní omezení (špatný formát, příliš malý, málo souborů, neodpovídá vzoru), klient dostane zpětnou vazbu přímo v portálu. Neplatnou položku odeslat nemůže.

Jediným zdrojem pravdy je definice položky od agenta — type, constraints a schema. BriefGate omezení nedovozuje z obsahu souboru ani jinou heuristikou. Když potřebujete omezení zpřísnit poté, co je intake živý, přidejte přes add_items náhradní položku s novým key a přes request_revision klienta k novému poli nasměrujte.