@lessly/sdk-app 83.4.0 → 85.0.0

package/src/gen/types.gen.ts

@@ -90532,6 +90532,378 @@ export interface OrganizationYoutubeInstallOutput {
 url: string
 }
 
+export interface PlaygroundAnalyticsOverviewInput {
+/**
+ * Max records per entity in recent[]; omit for the endpoint default
+ */
+limit?: number
+}
+
+export interface PlaygroundAnalyticsOverviewOutput {
+ok: boolean
+minted: boolean
+overview?: unknown
+http_status: number
+}
+
+export interface PlaygroundBillingEntitlementsInput {
+
+}
+
+export interface PlaygroundBillingEntitlementsOutput {
+ok: boolean
+minted: boolean
+http_status: number
+entitlements?: unknown
+}
+
+export interface PlaygroundBillingRecordUsageInput {
+/**
+ * Quantity of events to record against playground-events (SUM); defaults to 1
+ */
+value?: number
+}
+
+export interface PlaygroundBillingRecordUsageOutput {
+minted: boolean
+accepted: (number | null)
+recorded: boolean
+duplicates: (number | null)
+http_status: number
+}
+
+export interface PlaygroundClickupCreateTaskInput {
+/**
+ * Task title; defaults to a fixture label
+ */
+name?: string
+/**
+ * ClickUp list id; falls back to CLICKUP_TEST_LIST_ID
+ */
+listId?: string
+}
+
+export interface PlaygroundClickupCreateTaskOutput {
+minted: boolean
+task_id: (string | null)
+list_status: number
+vend_status: number
+clickup_status: number
+installation_count: number
+}
+
+export interface PlaygroundClickupGetLastWebhookInput {
+
+}
+
+export type PlaygroundClickupGetLastWebhookOutput = ({
+payload: string
+event_id: string
+provider: string
+verified: boolean
+product_id: string
+occurred_at: string
+connector_id: string
+clickup_event: (string | null)
+receipt_count: number
+} | {
+found: false
+})
+
+export interface PlaygroundClickupGetOverviewInput {
+
+}
+
+export interface PlaygroundClickupGetOverviewOutput {
+team: ({
+teamId: string
+teamName: string
+} | null)
+lists: PlaygroundClickupGetOverviewOutputItems[]
+tasks: {
+id: string
+name: string
+status: (string | null)
+}[]
+minted: boolean
+spaces: PlaygroundClickupGetOverviewOutputItems[]
+list_status: number
+vend_status: number
+lists_status: number
+tasks_status: number
+spaces_status: number
+folders_status: number
+installation_count: number
+}
+export interface PlaygroundClickupGetOverviewOutputItems {
+id: string
+name: string
+}
+
+export interface PlaygroundEchoPingInput {
+/**
+ * The text to echo back, 1–1024 characters
+ */
+message: string
+}
+
+export interface PlaygroundEchoPingOutput {
+/**
+ * The message exactly as it was received
+ */
+message: string
+/**
+ * The product the call was resolved to
+ */
+productId: string
+/**
+ * ISO-8601 instant (UTC) at which the call reached the service
+ */
+receivedAt: string
+}
+
+export interface PlaygroundGdriveGetLastChangeInput {
+
+}
+
+export type PlaygroundGdriveGetLastChangeOutput = ({
+file_id: string
+removed: boolean
+file_name: (string | null)
+mime_type: (string | null)
+product_id: string
+occurred_at: string
+connector_id: string
+resource_state: string
+} | {
+found: false
+})
+
+export interface PlaygroundGdriveReadFileInput {
+/**
+ * Drive file id; falls back to GDRIVE_TEST_FILE_ID, then the first picked file
+ */
+fileId?: string
+}
+
+export interface PlaygroundGdriveReadFileOutput {
+minted: boolean
+file_id: (string | null)
+file_name: (string | null)
+mime_type: (string | null)
+file_count: number
+get_status: number
+list_status: number
+vend_status: number
+content_bytes: (number | null)
+}
+
+export interface PlaygroundGoogleadsReadCustomerInput {
+
+}
+
+export interface PlaygroundGoogleadsReadCustomerOutput {
+minted: boolean
+vended: boolean
+customer_id: (string | null)
+vend_status: number
+result_count: number
+search_status: number
+login_customer_id: (string | null)
+}
+
+export interface PlaygroundLifecycleGetStateInput {
+
+}
+
+export interface PlaygroundLifecycleGetStateOutput {
+blocked: boolean
+archived: boolean
+productId: string
+lastBlockTransition: ({
+eventId: string
+eventName: string
+productId: string
+occurredAt: string
+recordedAt: string
+receiptCount: number
+organizationId: string
+cascadedFromOrg: boolean
+} | null)
+lastArchiveTransition: ({
+eventId: string
+eventName: string
+productId: string
+occurredAt: string
+recordedAt: string
+receiptCount: number
+organizationId: string
+cascadedFromOrg: boolean
+} | null)
+}
+
+export interface PlaygroundLifecycleListEventsInput {
+
+}
+
+export type PlaygroundLifecycleListEventsOutput = {
+eventId: string
+eventName: string
+productId: string
+occurredAt: string
+recordedAt: string
+receiptCount: number
+organizationId: string
+cascadedFromOrg: boolean
+}[]
+
+export interface PlaygroundWebhookGetLastInput {
+
+}
+
+export type PlaygroundWebhookGetLastOutput = ({
+payload?: unknown
+event_id: string
+provider: string
+verified: boolean
+product_id: string
+occurred_at: string
+connector_id: string
+delivery_count: number
+} | {
+found: false
+})
+
+export interface PlaygroundWorkflowEchoInput {
+/**
+ * The text to store, 1–1024 characters
+ */
+note: string
+/**
+ * Optional labels stored alongside the note, at most 20
+ * 
+ * @maxItems 20
+ */
+tags?: []|[string]|[string, string]|[string, string, string]|[string, string, string, string]|[string, string, string, string, string]|[string, string, string, string, string, string]|[string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]|[string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string]
+}
+
+export interface PlaygroundWorkflowEchoOutput {
+/**
+ * Identifier of the stored echo
+ */
+id: string
+/**
+ * The note exactly as it was received
+ */
+note: string
+/**
+ * The tags exactly as they were received
+ */
+tags: string[]
+/**
+ * Correlation id for this echo. The playground/workflow.echoed event published about two seconds later repeats it, which is how a composer matches the completion back to this step.
+ */
+echo_id: string
+/**
+ * ISO-8601 instant (UTC) at which the echo was stored
+ */
+received_at: string
+}
+
+export interface PlaygroundWorkflowEchoListInput {
+
+}
+
+export type PlaygroundWorkflowEchoListOutput = {
+/**
+ * Identifier of the stored echo
+ */
+id: string
+/**
+ * The note exactly as it was received
+ */
+note: string
+/**
+ * The tags exactly as they were received
+ */
+tags: string[]
+/**
+ * ISO-8601 instant (UTC) at which the echo was stored
+ */
+received_at: string
+}[]
+
+export interface PlaygroundWorkflowPingInput {
+/**
+ * Class of ping, echoed on the emitted event and filterable on the trigger. Defaults to 'manual'.
+ */
+kind?: string
+}
+
+export interface PlaygroundWorkflowPingOutput {
+/**
+ * Correlation id for this ping. The emitted playground/workflow.ping event repeats it, which is how a composer matches the event back to this step.
+ */
+id: string
+/**
+ * The name of the event that was published
+ */
+event: string
+}
+
+export interface PlaygroundWorkflowSubjectsListInput {
+/**
+ * How many subjects to return, 1–100. Defaults to 25.
+ */
+limit?: number
+/**
+ * The next_cursor of the previous page. Opaque — pass it back unchanged. Omit for the first page.
+ */
+cursor?: string
+/**
+ * ISO-8601 UTC instant. Return only subjects whose last_activity_at is AT OR AFTER this — the opposite question, the recently active population. Omit for no lower bound.
+ */
+last_activity_after?: string
+/**
+ * ISO-8601 UTC instant. Return only subjects whose last_activity_at is AT OR BEFORE this — the "inactive for N days" question: pass now minus N days. Omit for no upper bound.
+ */
+last_activity_before?: string
+}
+
+export interface PlaygroundWorkflowSubjectsListOutput {
+/**
+ * This page of subjects, most recently active first
+ */
+items: {
+/**
+ * Stable identifier for the subject. This is the field a batch trigger keys on, so a subject already served in an earlier run is skipped rather than served twice.
+ */
+subject_key: string
+/**
+ * Human-readable name of the subject
+ */
+display_name: string
+/**
+ * ISO-8601 instant (UTC) of the subject last activity
+ */
+last_activity_at: string
+}[]
+/**
+ * Whether another page follows. False and a null next_cursor both mark the last page, so a consumer that loops on either terminates.
+ */
+has_more: boolean
+/**
+ * Pass back as `cursor` to fetch the next page; null on the last page. Always null when has_more is false.
+ */
+next_cursor: (string | null)
+}
+
+export interface PlaygroundWsEchoInput {
+
+}
+
+export type PlaygroundWsEchoOutput = unknown;
+
 export interface RealtimeArchiveExportInput {
 /**
  * Only entries with ts <= to_ts (epoch ms)
@@ -112241,54 +112613,150 @@ secretPrefix: string
 }
 
 export interface TrackingDomainsCreateInput {
+/**
+ * Bare hostname to serve tracking from, which must sit under the chosen domain (e.g. analytics.example.com); a suggestion is used when omitted
+ */
 host?: string
+/**
+ * DNS records to request instead of the default CNAME to the tracking edge; leave unset unless the domain needs custom records
+ */
 records?: {
+/**
+ * Time-to-live in seconds the record should be published with; the platform picks one when omitted
+ */
 ttl?: number
+/**
+ * Fully-qualified host the record is published at; defaults to the claimed tracking host
+ */
 name?: string
+/**
+ * Value the record points at — the edge hostname for a CNAME, the proof string for a TXT
+ */
 target: string
+/**
+ * DNS record type to publish, e.g. CNAME or TXT
+ */
 recordType: string
 }[]
+/**
+ * Product domain to claim the tracking host under, as listed in `domains[].domainId` by tracking_domains_list
+ */
 domainId: string
 }
 
 export interface TrackingDomainsCreateOutput {
+/**
+ * The binding as just claimed; it starts `pending` and goes `active` once the DNS is observed live
+ */
 binding: {
+/**
+ * Fully-qualified tracking host this binding serves, e.g. analytics.example.com
+ */
 host: string
+/**
+ * Where the claim stands: `pending` while DNS has not been observed live, `active` once it serves, `failed` when the check gave up
+ */
 status: ("pending" | "active" | "failed")
+/**
+ * DNS records the platform expects to see published for this host, as returned when the binding was claimed
+ */
 records: unknown[]
+/**
+ * Product domain this tracking host sits under
+ */
 domainId: string
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
+/**
+ * When the binding was claimed
+ */
 createdAt: string
+/**
+ * Product the binding belongs to
+ */
 productId: string
+/**
+ * When the binding last changed status or records
+ */
 updatedAt: string
+/**
+ * Human-readable reason behind the current status, such as the DNS error that made it fail; null while there is nothing to report
+ */
 statusDetail: (string | null)
+/**
+ * Extension that claimed the binding; tracking bindings are owned by this toolkit
+ */
 ownerExtension: string
 }
+/**
+ * Ordered, human-readable steps for publishing the DNS the claim needs; empty when the platform manages the domain itself
+ */
 instructions: string[]
 }
 
 export interface TrackingDomainsDeleteInput {
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
 }
 
 export interface TrackingDomainsDeleteOutput {
+/**
+ * Always true — the release succeeded; a failure arrives as an error, not as false
+ */
 ok: true
 }
 
 export interface TrackingDomainsGetInput {
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
 }
 
 export interface TrackingDomainsGetOutput {
+/**
+ * Fully-qualified tracking host this binding serves, e.g. analytics.example.com
+ */
 host: string
+/**
+ * Where the claim stands: `pending` while DNS has not been observed live, `active` once it serves, `failed` when the check gave up
+ */
 status: ("pending" | "active" | "failed")
+/**
+ * DNS records the platform expects to see published for this host, as returned when the binding was claimed
+ */
 records: unknown[]
+/**
+ * Product domain this tracking host sits under
+ */
 domainId: string
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
+/**
+ * When the binding was claimed
+ */
 createdAt: string
+/**
+ * Product the binding belongs to
+ */
 productId: string
+/**
+ * When the binding last changed status or records
+ */
 updatedAt: string
+/**
+ * Human-readable reason behind the current status, such as the DNS error that made it fail; null while there is nothing to report
+ */
 statusDetail: (string | null)
+/**
+ * Extension that claimed the binding; tracking bindings are owned by this toolkit
+ */
 ownerExtension: string
 }
 
@@ -112297,41 +112765,125 @@ export interface TrackingDomainsListInput {
 }
 
 export interface TrackingDomainsListOutput {
+/**
+ * The product's domains as the platform vouches for them — the set a new tracking host may be claimed under
+ */
 domains: {
+/**
+ * Who runs the DNS: `managed` means the platform publishes records for you, `external` means you publish them yourself
+ */
 mode: ("external" | "managed")
+/**
+ * Apex domain name the product owns, e.g. example.com
+ */
 domain: string
+/**
+ * Stable platform id of the product domain, and what a claim takes as its `domainId`
+ */
 domainId: string
+/**
+ * ISO-8601 timestamp of when the domain was added to the product
+ */
 createdAt: string
+/**
+ * How many extensions currently hold a host binding under this domain
+ */
 extensionCount: number
 }[]
+/**
+ * Tracking-host bindings this toolkit currently holds across those domains
+ */
 bindings: {
+/**
+ * Fully-qualified tracking host this binding serves, e.g. analytics.example.com
+ */
 host: string
+/**
+ * Where the claim stands: `pending` while DNS has not been observed live, `active` once it serves, `failed` when the check gave up
+ */
 status: ("pending" | "active" | "failed")
+/**
+ * DNS records the platform expects to see published for this host, as returned when the binding was claimed
+ */
 records: unknown[]
+/**
+ * Product domain this tracking host sits under
+ */
 domainId: string
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
+/**
+ * When the binding was claimed
+ */
 createdAt: string
+/**
+ * Product the binding belongs to
+ */
 productId: string
+/**
+ * When the binding last changed status or records
+ */
 updatedAt: string
+/**
+ * Human-readable reason behind the current status, such as the DNS error that made it fail; null while there is nothing to report
+ */
 statusDetail: (string | null)
+/**
+ * Extension that claimed the binding; tracking bindings are owned by this toolkit
+ */
 ownerExtension: string
 }[]
 }
 
 export interface TrackingDomainsVerifyInput {
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
 }
 
 export interface TrackingDomainsVerifyOutput {
+/**
+ * Fully-qualified tracking host this binding serves, e.g. analytics.example.com
+ */
 host: string
+/**
+ * Where the claim stands: `pending` while DNS has not been observed live, `active` once it serves, `failed` when the check gave up
+ */
 status: ("pending" | "active" | "failed")
+/**
+ * DNS records the platform expects to see published for this host, as returned when the binding was claimed
+ */
 records: unknown[]
+/**
+ * Product domain this tracking host sits under
+ */
 domainId: string
+/**
+ * Id of the tracking-host binding to act on, as returned in `bindings[].bindingId` by tracking_domains_list
+ */
 bindingId: string
+/**
+ * When the binding was claimed
+ */
 createdAt: string
+/**
+ * Product the binding belongs to
+ */
 productId: string
+/**
+ * When the binding last changed status or records
+ */
 updatedAt: string
+/**
+ * Human-readable reason behind the current status, such as the DNS error that made it fail; null while there is nothing to report
+ */
 statusDetail: (string | null)
+/**
+ * Extension that claimed the binding; tracking bindings are owned by this toolkit
+ */
 ownerExtension: string
 }
 
@@ -112343,7 +112895,13 @@ name: string
 }
 
 export interface TrackingEventNamesArchiveOutput {
+/**
+ * Event name whose status was changed
+ */
 name: string
+/**
+ * The status as it now stands: `archived` hides the name from pickers and reports, `active` restores it
+ */
 status: ("active" | "archived")
 }
 
@@ -112367,13 +112925,37 @@ status?: ("active" | "archived")
 }
 
 export interface TrackingEventNamesListOutput {
+/**
+ * The matching catalogue entries, ordered by the requested sort
+ */
 names: {
+/**
+ * Event name exactly as the tracking script sends it — the string other tools take as their `event`
+ */
 name: string
+/**
+ * How many events with this name have been received in total
+ */
 count: number
+/**
+ * `active` for a name in use, `archived` for one hidden from pickers and reports
+ */
 status: string
+/**
+ * ISO-8601 timestamp of the most recent event received under this name
+ */
 lastSeen: string
+/**
+ * ISO-8601 timestamp of the first event ever received under this name
+ */
 firstSeen: string
+/**
+ * Property keys sampled from recent events with this name, so you can see what the payload carries
+ */
 propsKeys: string[]
+/**
+ * Whether this name is marked a conversion, which is what makes it available as a workflow trigger
+ */
 isConversion: boolean
 }[]
 }
@@ -112390,7 +112972,13 @@ isConversion: boolean
 }
 
 export interface TrackingEventNamesSetConversionOutput {
+/**
+ * Event name the conversion flag was applied to
+ */
 name: string
+/**
+ * The flag as it now stands after the change
+ */
 isConversion: boolean
 }
 
@@ -112402,7 +112990,13 @@ name: string
 }
 
 export interface TrackingEventNamesUnarchiveOutput {
+/**
+ * Event name whose status was changed
+ */
 name: string
+/**
+ * The status as it now stands: `archived` hides the name from pickers and reports, `active` restores it
+ */
 status: ("active" | "archived")
 }
 
@@ -112411,14 +113005,32 @@ export interface TrackingGoogleadsConnectionStatusInput {
 }
 
 export type TrackingGoogleadsConnectionStatusOutput = ({
+/**
+ * Where the Google Ads connection stands: connected means an account is chosen and its credential works, so the other tools will run.
+ */
 state: "connected"
+/**
+ * The Google Ads account the data is read from and conversions are written to, as a customer id. Only present while connected.
+ */
 customerId: string
+/**
+ * The manager account the connection authenticates through, as a Google customer id. Same as customerId when the account is not managed. Only present while connected.
+ */
 loginCustomerId: string
 } | {
+/**
+ * Google is authorised but nobody has picked which Google Ads account to use yet, so nothing can run until someone does.
+ */
 state: "pending_account_selection"
 } | {
+/**
+ * The Google authorisation expired or was revoked and has to be granted again before anything can run.
+ */
 state: "reauth_required"
 } | {
+/**
+ * No Google Ads connection has been set up for this product at all.
+ */
 state: "not_connected"
 })
 
@@ -112439,26 +113051,77 @@ export interface TrackingGoogleadsFeedbackConfigGetInput {
 }
 
 export interface TrackingGoogleadsFeedbackConfigGetOutput {
+/**
+ * How the uploads coexist with the account's own tag: existing_pixel means the Google tag also records these conversions, so send only to actions the tag does not already cover; fresh_pixel means these uploads are the only source.
+ */
 mode: ("existing_pixel" | "fresh_pixel")
+/**
+ * Which tracked events become which Google Ads conversion action, and where each one takes its money value from. Disabled rules stay listed.
+ */
 rules: {
+/**
+ * Tracked event-name this rule uploads, as listed by tracking_event-names_list
+ */
 event: string
+/**
+ * What monetary value is reported to Google for each conversion this rule uploads
+ */
 value: ({
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "revenue"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "dynamic"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "fixed"
+/**
+ * ISO-4217 currency the fixed amount is denominated in, e.g. USD
+ */
 currency: string
+/**
+ * The fixed value in minor units (e.g. cents); 0 means a value-less lead conversion
+ */
 amountMinor: number
 })
+/**
+ * Whether this single mapping is live; a disabled rule is kept but uploads nothing
+ */
 enabled: boolean
+/**
+ * Google conversion action the event is reported as, in the form customers/<cid>/conversionActions/<id>
+ */
 conversionAction: string
 }[]
+/**
+ * Whether conversions are being sent to Google Ads at all. False leaves every rule below in place but uploads nothing.
+ */
 enabled: boolean
+/**
+ * The tenant this configuration belongs to. Never supplied by a caller — it comes from the authenticated identity.
+ */
 productId: string
+/**
+ * How many days back each pass looks for conversions to send, and how far back a click may be matched. Google rejects clicks older than about 90 days.
+ */
 lookbackDays: number
+/**
+ * Currency of the connected Google Ads account, as a three-letter ISO 4217 code such as EUR. Null when the account could not be read.
+ */
 accountCurrency: (string | null)
+/**
+ * The event names that may use the Dynamic value source, because revenue is known for them. Any other event needs a fixed amount.
+ */
 dynamicValueEvents: string[]
+/**
+ * Whether a stored email or phone number is sent alongside the click, so Google can match conversions the click id alone would miss.
+ */
 enhancedConversions: boolean
 }
 
@@ -112475,11 +113138,23 @@ rules?: {
  * Any tracked event-name for this product (validated against the event-name catalog)
  */
 event: string
+/**
+ * What monetary value to report to Google for each conversion this rule uploads
+ */
 value: ({
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "revenue"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "dynamic"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "fixed"
 /**
  * ISO-4217 currency code, e.g. USD
@@ -112490,6 +113165,9 @@ currency: string
  */
 amountMinor?: number
 })
+/**
+ * Whether this single mapping is live; a disabled rule is kept but uploads nothing
+ */
 enabled: boolean
 /**
  * Google conversion action resource: customers/<cid>/conversionActions/<id>
@@ -112511,28 +113189,82 @@ enhancedConversions?: boolean
 }
 
 export interface TrackingGoogleadsFeedbackConfigSetOutput {
+/**
+ * The config as it now stands after the write, with server-side normalisation applied
+ */
 config: {
+/**
+ * How our uploads sit beside your own tag: `existing_pixel` only fills gaps it left, `fresh_pixel` reports our data alone
+ */
 mode: ("existing_pixel" | "fresh_pixel")
+/**
+ * The event-to-conversion-action mappings, each with its own value source
+ */
 rules: {
+/**
+ * Tracked event-name this rule uploads, as listed by tracking_event-names_list
+ */
 event: string
+/**
+ * What monetary value is reported to Google for each conversion this rule uploads
+ */
 value: ({
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "revenue"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "dynamic"
 } | {
+/**
+ * Where the conversion value comes from: `revenue` uses the net revenue of the subscription, `dynamic` reads the amount carried by the occurrence itself, `fixed` always sends the same amount
+ */
 source: "fixed"
+/**
+ * ISO-4217 currency the fixed amount is denominated in, e.g. USD
+ */
 currency: string
+/**
+ * The fixed value in minor units (e.g. cents); 0 means a value-less lead conversion
+ */
 amountMinor: number
 })
+/**
+ * Whether this single mapping is live; a disabled rule is kept but uploads nothing
+ */
 enabled: boolean
+/**
+ * Google conversion action the event is reported as, in the form customers/<cid>/conversionActions/<id>
+ */
 conversionAction: string
 }[]
+/**
+ * Master switch: with it off no rule uploads anything, however the individual rules are set
+ */
 enabled: boolean
+/**
+ * Product this conversion-feedback config belongs to
+ */
 productId: string
+/**
+ * How many days back a click may have happened and still be matched to a conversion (max 90)
+ */
 lookbackDays: number
+/**
+ * The connected Google Ads account's currency, best-effort; null or absent when it could not be read
+ */
 accountCurrency?: (string | null)
+/**
+ * Whether hashed email and phone are sent alongside gclid as additional match keys, which raises match rates
+ */
 enhancedConversions: boolean
 }
+/**
+ * Plain-language safety notes about what this combination of mode and match keys will do to the connected account
+ */
 guidance: string[]
 }
 
@@ -112541,15 +113273,48 @@ export interface TrackingGoogleadsFeedbackRunInput {
 }
 
 export interface TrackingGoogleadsFeedbackRunOutput {
+/**
+ * This one upload pass. Match the completion event back to this step on it, not on productId: the daily cron pass and a manual run on the same day are two passes of the same product.
+ */
+runId: string
+/**
+ * Rows Google rejected in this pass.
+ */
 failed: number
+/**
+ * Of those, the ones that had a usable click id and a value, so a payload was actually built for them.
+ */
 matched: number
+/**
+ * Conversions dropped because no Google click could be tied to the person. A high count here is a tagging problem, not a Google one.
+ */
 noGclid: number
+/**
+ * Present only when the pass did no work, and says why: feedback is switched off, no rule is enabled, or no Google Ads account is connected. Absent on a pass that ran.
+ */
 skipped?: ("disabled" | "no_rules" | "not_connected")
+/**
+ * Conversions in the lookback window that an enabled rule applied to.
+ */
 selected: number
+/**
+ * Rows Google accepted in this pass.
+ */
 uploaded: number
+/**
+ * The tenant whose conversions this pass uploaded.
+ */
 productId: string
+/**
+ * Conversions held back because their money value had not landed yet. They are retried on a later pass.
+ */
 zeroValue: number
-partialFailureError?: unknown
+/**
+ * Google's own rejection detail, passed through unchanged, when it refused part of the batch. Absent when it accepted everything.
+ */
+partialFailureError?: {
+[k: string]: unknown
+}
 }
 
 export interface TrackingGoogleadsFeedbackStatusInput {
@@ -112557,25 +113322,82 @@ export interface TrackingGoogleadsFeedbackStatusInput {
 }
 
 export interface TrackingGoogleadsFeedbackStatusOutput {
+/**
+ * How the uploads coexist with the account's own tag: existing_pixel means the Google tag also records these conversions; fresh_pixel means these uploads are the only source.
+ */
 mode: ("existing_pixel" | "fresh_pixel")
+/**
+ * Rows Google has rejected since this product was connected, across every pass.
+ */
 failed: number
+/**
+ * Whether conversions are being sent to Google Ads at all.
+ */
 enabled: boolean
+/**
+ * Coverage of the most recent pass. Null when no pass has run for this product yet.
+ */
 lastRun: ({
+/**
+ * When the last pass finished. Null when the stored summary predates this field.
+ */
 ranAt: (string | null)
+/**
+ * Rows Google rejected. Anything above zero is what makes the status partial.
+ */
 failed: number
+/**
+ * How the pass ended: ok is a clean pass, partial means Google rejected some rows and accepted others, not_connected means no Google Ads account was reachable and nothing was sent.
+ */
 status: ("ok" | "partial" | "not_connected")
+/**
+ * Of those, the ones that had a usable click id and a value, so a payload was actually built for them.
+ */
 matched: number
+/**
+ * Conversions dropped because no Google click could be tied to the person. A high count here is a tagging problem, not a Google one.
+ */
 noGclid: number
+/**
+ * Conversions in the lookback window that an enabled rule applied to.
+ */
 selected: number
+/**
+ * Rows Google accepted.
+ */
 uploaded: number
+/**
+ * Conversions held back because their money value had not landed yet. They are retried on a later pass.
+ */
 zeroValue: number
 } | null)
+/**
+ * Plain-language warnings about the current setup, such as double counting when the Google tag already records the same conversion. Empty when nothing needs saying.
+ */
 guidance: string[]
+/**
+ * Rows Google has accepted since this product was connected, across every pass.
+ */
 uploaded: number
+/**
+ * How many event-to-conversion-action rules are configured, enabled or not.
+ */
 ruleCount: number
+/**
+ * How many days back each pass looks for conversions to send, and how far back a click may be matched.
+ */
 lookbackDays: number
+/**
+ * Currency of the connected Google Ads account, as a three-letter ISO 4217 code such as EUR. Null when the account could not be read.
+ */
 accountCurrency: (string | null)
-dynamicValueEvents: string[]
+/**
+ * The event names that may use the Dynamic value source, because revenue is known for them.
+ */
+dynamicValueEvents: string[]
+/**
+ * Whether a stored email or phone number is sent alongside the click, so Google can match conversions the click id alone would miss.
+ */
 enhancedConversions: boolean
 }
 
@@ -112597,65 +113419,228 @@ conversionDatetime: string
 }[]
 
 export interface TrackingGoogleadsRoasReportInput {
-to: string
-from: string
+/**
+ * End of the reporting window, inclusive. ISO-8601 date or timestamp; a date-only value covers that whole day, so revenue after midnight is not cut off. Omit to end now.
+ */
+to?: string
+/**
+ * Start of the reporting window, inclusive. ISO-8601 date or timestamp, e.g. 2026-01-01. Omit to start 30 days before the end of the window.
+ */
+from?: string
+/**
+ * Which touchpoint gets the credit for a conversion: the last paid click before it, or the first. Defaults to last_click.
+ */
 model?: ("last_click" | "first_click")
+/**
+ * Restrict to conversions tracked on this installed site, e.g. acme.com. Omit to cover every domain of the product.
+ */
 domain?: string
+/**
+ * Restrict to one Google Ads account, by its customer id without dashes. Omit to cover every connected account.
+ */
 customerId?: string
+/**
+ * How far back before a conversion a paid click may sit and still earn the credit, in days. 1-365, silently clamped into that range; defaults to 30.
+ */
 lookbackDays?: number
 }
 
 export interface TrackingGoogleadsRoasReportOutput {
+/**
+ * End of the window this report covers, echoed back as an ISO-8601 UTC timestamp.
+ */
 to: string
+/**
+ * Start of the window this report covers, echoed back as an ISO-8601 UTC timestamp.
+ */
 from: string
+/**
+ * Which touchpoint earned the credit in these numbers: the last paid click before the conversion, or the first.
+ */
 model: ("last_click" | "first_click")
+/**
+ * True when any account below is running on cost older than the freshness threshold, or on no cost at all — read this before acting on the numbers.
+ */
+stale: boolean
+/**
+ * The installed site this report was restricted to; null when it covers every domain of the product.
+ */
 domain: (string | null)
+/**
+ * One entry per Google Ads account and currency. Kept apart on purpose: amounts in different currencies are never added together.
+ */
 accounts: {
+/**
+ * True when this account's cost is older than the freshness threshold, or was never pulled — the ROAS below is then built on outdated spend.
+ */
 stale: boolean
+/**
+ * ISO-4217 code every amount under this account is expressed in, e.g. USD. One account appears once per currency its cost was booked in.
+ */
 currency: string
+/**
+ * This account's campaigns, each with its ad groups and ads nested underneath.
+ */
 campaigns: TrackingGoogleadsRoasReportOutputItems[]
+/**
+ * Google Ads account these campaigns belong to, by customer id without dashes.
+ */
 customerId: string
+/**
+ * When cost was last pulled from Google Ads for this account (ISO-8601 UTC); null when it has never been pulled.
+ */
 costLastSyncedAt: (string | null)
 }[]
+/**
+ * ISO-4217 code every amount in this report is expressed in, when all accounts share one; null when the report spans several currencies.
+ */
+currency: (string | null)
+/**
+ * When this report was calculated (ISO-8601 UTC). The figures are a snapshot at this moment, not live.
+ */
 computedAt: string
+/**
+ * Google Ads account this whole report covers, when it covers exactly one; null when it spans several accounts.
+ */
+customerId: (string | null)
+/**
+ * How far back before a conversion a paid click was allowed to sit and still earn the credit, in days.
+ */
 lookbackDays: number
+/**
+ * Oldest moment cost was pulled from Google Ads across the accounts below (ISO-8601 UTC); null when any account has never synced.
+ */
+costLastSyncedAt: (string | null)
+/**
+ * Revenue we tracked but could not tie to any Google Ads campaign, grouped by the utm_campaign we saw. A long list here means the ad tagging needs fixing, not that the ads failed.
+ */
 unmatchedAttributed: {
+/**
+ * Revenue that stayed outside every campaign, one row per currency. Never cross-summed.
+ */
 revenue: TrackingGoogleadsRoasReportOutputItems1[]
+/**
+ * How many distinct customers paid but could not be traced to any Google Ads campaign.
+ */
 conversions: number
+/**
+ * The utm_campaign value we saw on the visit, which matched no Google Ads campaign; null when the visit carried none. This is the diagnostic: fix the tagging and the revenue moves into a campaign.
+ */
 utmCampaign: (string | null)
 }[]
 }
 export interface TrackingGoogleadsRoasReportOutputItems {
+/**
+ * What one attributed customer cost: cost divided by attributed conversions, in minor units of the account currency. null when there were no attributed conversions.
+ */
 cpa: (number | null)
+/**
+ * Google Ads ad this node is, by its numeric id; null on a campaign or ad group node.
+ */
 adId: (string | null)
+/**
+ * What Google charged and what Google itself counted for this node over the window.
+ */
 cost: {
+/**
+ * How many times someone clicked through from Google over the window.
+ */
 clicks: number
+/**
+ * ISO-4217 code of the Google Ads account these numbers come from, e.g. USD. Fixed per account.
+ */
 currency: string
+/**
+ * What Google charged for this campaign, ad group or ad over the window, in minor units (1250 = 12.50).
+ */
 costMinor: number
+/**
+ * How many times Google showed this ad over the window.
+ */
 impressions: number
+/**
+ * Conversions GOOGLE counted for this node — its own attribution, not ours. May be fractional, because Google splits credit across touchpoints.
+ */
 platformConversions: number
+/**
+ * Conversion value GOOGLE reports for this node, in minor units of the account currency. Compare it with our attributed revenue; the two rarely agree.
+ */
 platformConversionsValueMinor: number
 }
+/**
+ * What this campaign, ad group or ad is called in Google Ads; null when the name has not been synced.
+ */
 name: (string | null)
+/**
+ * Return on ad spend: our net attributed revenue divided by cost, both in the account currency. A plain ratio, not a percentage — 2.4 means 2.40 back per 1.00 spent. null when cost is 0 or nothing was attributed.
+ */
 roas: (number | null)
+/**
+ * How deep in the Google Ads hierarchy this node sits. Attributed revenue, ROAS and CPA exist at campaign level only; cost exists at all three.
+ */
 level: ("campaign" | "ad_group" | "ad")
+/**
+ * Google Ads campaign state, passed through raw: ENABLED, PAUSED, REMOVED. Present on campaign nodes only — the key is absent below.
+ */
 status?: string
+/**
+ * The level below this one: ad groups under a campaign, ads under an ad group, empty on an ad.
+ */
 children: TrackingGoogleadsRoasReportOutputItems[]
+/**
+ * Google Ads ad group this node belongs to, by its numeric id; null on a campaign node.
+ */
 adGroupId: (string | null)
+/**
+ * What WE traced back to this node from our own tracking. null below campaign level, and null on a campaign nothing was traced to.
+ */
 attributed: ({
+/**
+ * What WE traced back to this campaign, one row per currency the customers paid in. Never cross-summed — use accountCurrencyNetMinor for a single figure.
+ */
 revenue: TrackingGoogleadsRoasReportOutputItems1[]
-matchedBy: (("campaign_id" | "campaign_name" | "gclid") | null)
+/**
+ * Which key actually joined this revenue to the Google campaign, strongest first: lt_campaign_id (the id our own tracking template stamps on the landing URL), campaign_id (the id inside utm_campaign), campaign_name (the campaign name inside utm_campaign, a guess), gclid (the click id). null means the join key is unknown; treat campaign_name as the weakest evidence.
+ */
+matchedBy: (("lt_campaign_id" | "campaign_id" | "campaign_name" | "gclid") | null)
+/**
+ * How many distinct customers we traced back to this campaign over the window. Whole numbers: we give a conversion to one campaign, we never split it.
+ */
 conversions: number
+/**
+ * Our net attributed revenue in the account currency alone, in minor units. 0 when nobody paid in that currency. This is the ROAS numerator, and the single-value answer beside the revenue list.
+ */
 accountCurrencyNetMinor: number
 } | null)
+/**
+ * Google Ads campaign this node belongs to, by its numeric id. Set at every level.
+ */
 campaignId: string
+/**
+ * Google Ads account this node belongs to, by customer id without dashes.
+ */
 customerId: string
+/**
+ * Where Google ran the campaign, passed through raw: SEARCH, DISPLAY, VIDEO, PERFORMANCE_MAX and so on. Present on campaign nodes only, and may be null there.
+ */
 channelType?: (string | null)
 }
 export interface TrackingGoogleadsRoasReportOutputItems1 {
+/**
+ * ISO-4217 code the three amounts on this row are denominated in, e.g. USD. One row per currency; rows are never added together.
+ */
 currency: string
+/**
+ * Money kept after refunds (gross minus refunded), in minor units of this row's currency. This is what ROAS is calculated from.
+ */
 netMinor: number
+/**
+ * Money taken before refunds, in minor units of this row's currency (1250 = 12.50).
+ */
 grossMinor: number
+/**
+ * Money given back within the window, in minor units of this row's currency; already subtracted from netMinor.
+ */
 refundedMinor: number
 }
 
@@ -112664,21 +113649,67 @@ export interface TrackingGoogleadsSyncNowInput {
 }
 
 export interface TrackingGoogleadsSyncNowOutput {
+/**
+ * How much this sweep wrote, split by what it wrote. Re-running the same window updates rows in place rather than adding, so these are rows touched, not rows gained. All zero when the status is skipped.
+ */
 rows: {
+/**
+ * Ads written.
+ */
 ads: number
+/**
+ * Day-by-day ad spend and metric rows written.
+ */
 adDaily: number
+/**
+ * Ad groups written.
+ */
 adGroups: number
+/**
+ * Campaigns written, names and status included.
+ */
 campaigns: number
+/**
+ * Day-by-day ad-group spend and metric rows written.
+ */
 adGroupDaily: number
+/**
+ * Day-by-day campaign spend and metric rows written.
+ */
 campaignDaily: number
 }
+/**
+ * This one sync run. Match the completion event back to this step on it, not on productId: a product syncs many times, and the daily cron run and a manual one are different runs.
+ */
+runId: string
+/**
+ * Why nothing was written, when the status is skipped: the account is not chosen yet, the authorisation expired, or Google was unavailable. Absent on a sweep that ran.
+ */
 reason?: string
+/**
+ * Whether the sweep ran. skipped means the Google Ads account could not be reached and nothing at all was written.
+ */
 status: ("ok" | "skipped")
+/**
+ * The range of days this sweep read spend and metrics for.
+ */
 window: {
+/**
+ * Last day covered, inclusive, as YYYY-MM-DD.
+ */
 end: string
+/**
+ * First day covered, inclusive, as YYYY-MM-DD.
+ */
 start: string
 }
+/**
+ * The tenant whose Google Ads account was swept.
+ */
 productId: string
+/**
+ * When the sweep finished. Null when nothing was written.
+ */
 lastSyncedAt: (string | null)
 }
 
@@ -112694,54 +113725,187 @@ from?: string
 }
 
 export interface TrackingGoogleadsTrackingHealthOutput {
+/**
+ * End of the range these figures cover, as an instant.
+ */
 to: string
+/**
+ * Start of the range these figures cover, as an instant. Echoes back the range that was asked for.
+ */
 from: string
+/**
+ * Whether the tracking template has been seen working live: true once at least one tagged click has arrived.
+ */
 installed: boolean
+/**
+ * Whether the sample above was cut short. True means more untagged URLs exist than are listed.
+ */
 truncated: boolean
+/**
+ * Google paid clicks that arrived on the site in this range. The denominator for everything below.
+ */
 paidClicks: number
+/**
+ * How complete the figures above are. Holds no metric of its own — it exists so the breakage rate is not read as one uniform population.
+ */
 dataQuality: {
+/**
+ * Paid clicks from visitors who declined consent. Counted inside paidClicks, never added to it — a cookieless click is a real click. Clicks from sites running no consent banner are not counted here: nobody was asked, which is not the same as being told no.
+ */
 cookielessPaidClicks: number
 }
+/**
+ * Share of paid clicks that arrived untagged, between 0 and 1. Anything much above zero means the tracking template needs fixing.
+ */
 breakageRate: number
+/**
+ * Of those, the ones that arrived carrying our URL tracking parameters, so the campaign behind them is known.
+ */
 taggedClicks: number
+/**
+ * When the most recent untagged click arrived. Close to now means the breakage is still live. Null when none did.
+ */
 lastUntaggedAt: (string | null)
+/**
+ * Of those, the ones that arrived without our parameters, so the money spent on them cannot be attributed. This is what the tracking template being missing or broken looks like.
+ */
 untaggedClicks: number
+/**
+ * When the first untagged click of the range arrived — roughly when the breakage started. Null when none did.
+ */
 firstUntaggedAt: (string | null)
+/**
+ * A handful of the actual landing URLs that arrived untagged, to paste into a browser while fixing the template. Real customer URLs, query strings included.
+ */
 sampleUntaggedUrls: string[]
 }
 
 export interface TrackingGoogleadsUsVsPlatformInput {
-to: string
-from: string
+/**
+ * End of the reporting window, inclusive. ISO-8601 date or timestamp; a date-only value covers that whole day, so revenue after midnight is not cut off. Omit to end now.
+ */
+to?: string
+/**
+ * Start of the reporting window, inclusive. ISO-8601 date or timestamp, e.g. 2026-01-01. Omit to start 30 days before the end of the window.
+ */
+from?: string
+/**
+ * Which touchpoint gets the credit for a conversion: the last paid click before it, or the first. Defaults to last_click.
+ */
 model?: ("last_click" | "first_click")
+/**
+ * Restrict to conversions tracked on this installed site, e.g. acme.com. Omit to cover every domain of the product.
+ */
 domain?: string
+/**
+ * Restrict to one Google Ads account, by its customer id without dashes. Omit to cover every connected account.
+ */
 customerId?: string
+/**
+ * How far back before a conversion a paid click may sit and still earn the credit, in days. 1-365, silently clamped into that range; defaults to 30.
+ */
 lookbackDays?: number
 }
 
 export interface TrackingGoogleadsUsVsPlatformOutput {
+/**
+ * End of the window this comparison covers, echoed back as an ISO-8601 UTC timestamp.
+ */
 to: string
+/**
+ * Start of the window this comparison covers, echoed back as an ISO-8601 UTC timestamp.
+ */
 from: string
+/**
+ * Which touchpoint earned the credit on OUR side of the comparison: the last paid click before the conversion, or the first. Google always uses its own model.
+ */
 model: ("last_click" | "first_click")
+/**
+ * True when any account below is running on cost older than the freshness threshold, or on no cost at all — read this before acting on the numbers.
+ */
+stale: boolean
+/**
+ * The installed site this comparison was restricted to; null when it covers every domain of the product.
+ */
 domain: (string | null)
+/**
+ * One entry per Google Ads account and currency, each holding its per-campaign comparison rows. Currencies are never added together.
+ */
 accounts: {
+/**
+ * One row per campaign in this account, ours beside Google's.
+ */
 rows: {
+/**
+ * What this campaign is called in Google Ads; null when the name has not been synced.
+ */
 name: (string | null)
+/**
+ * ISO-4217 code both sides of this comparison are expressed in, e.g. USD. Ours and Google's are never converted.
+ */
 currency: string
+/**
+ * The Google Ads campaign this row compares, by its numeric id.
+ */
 campaignId: string
+/**
+ * Google Ads account this campaign belongs to, by customer id without dashes.
+ */
 customerId: string
+/**
+ * How many distinct customers WE traced to this campaign. A whole number: we never split a customer across campaigns.
+ */
 ourConversions: number
+/**
+ * Net revenue WE traced to this campaign, in minor units of the account currency (1250 = 12.50). 0 when we traced none.
+ */
 ourRevenueNetMinor: number
+/**
+ * Conversions GOOGLE counted for the same campaign. May be fractional, because Google splits credit across touchpoints — which is the usual reason the two sides disagree.
+ */
 platformConversions: number
+/**
+ * Conversion value GOOGLE reports for the same campaign, in minor units of the account currency. The counterpart of ourRevenueNetMinor.
+ */
 platformConversionsValueMinor: number
 }[]
+/**
+ * True when this account's Google-side numbers are older than the freshness threshold, or were never pulled — the comparison is then unfair to one side.
+ */
 stale: boolean
+/**
+ * ISO-4217 code every amount under this account is expressed in, e.g. USD. One account appears once per currency its cost was booked in.
+ */
 currency: string
+/**
+ * Google Ads account these comparison rows belong to, by customer id without dashes.
+ */
 customerId: string
+/**
+ * When cost was last pulled from Google Ads for this account (ISO-8601 UTC); null when it has never been pulled.
+ */
 costLastSyncedAt: (string | null)
 }[]
+/**
+ * ISO-4217 code every amount in this report is expressed in, when all accounts share one; null when the report spans several currencies.
+ */
+currency: (string | null)
+/**
+ * When this comparison was calculated (ISO-8601 UTC). The figures are a snapshot at this moment, not live.
+ */
 computedAt: string
+/**
+ * Google Ads account this whole report covers, when it covers exactly one; null when it spans several accounts.
+ */
+customerId: (string | null)
+/**
+ * How far back before a conversion a paid click was allowed to sit and still earn the credit on our side, in days.
+ */
 lookbackDays: number
+/**
+ * Oldest moment cost was pulled from Google Ads across the accounts below (ISO-8601 UTC); null when any account has never synced.
+ */
+costLastSyncedAt: (string | null)
 }
 
 export interface TrackingIdentityHealthInput {
@@ -112749,11 +113913,29 @@ export interface TrackingIdentityHealthInput {
 }
 
 export interface TrackingIdentityHealthOutput {
+/**
+ * When these numbers were computed, ISO 8601 UTC. They are a live count, so this is effectively the moment of the call.
+ */
 computedAt: string
+/**
+ * How many people the product holds in total, anonymous ones included. The denominator of both rates below.
+ */
 totalProfiles: number
+/**
+ * Identified people as a share of the total, normally 0 to 1 (0.42 is 42%). A drop here usually means a broken identify() call, not fewer visitors.
+ */
 identifiedRate: number
+/**
+ * People with an ad touchpoint as a share of the total, normally 0 to 1. It counts click-id identifiers, so an identifier outliving its profile can push it just above 1 — read it as an indicator, not as a proportion to assert on.
+ */
 adTouchpointRate: number
+/**
+ * How many of them an email or phone is known for — the people a message can actually be sent to.
+ */
 identifiedProfiles: number
+/**
+ * How many people arrived carrying an ad click id. A proxy for paid reach: it counts anyone with at least one click id on record.
+ */
 adTouchpointProfiles: number
 }
 
@@ -112765,6 +113947,9 @@ domain: string
 }
 
 export interface TrackingInstallDomainsCreateOutput {
+/**
+ * The domain as stored after normalisation, which may differ from what was submitted
+ */
 domain: string
 }
 
@@ -112776,6 +113961,9 @@ domain: string
 }
 
 export interface TrackingInstallDomainsDeleteOutput {
+/**
+ * Always true — the domain was removed; a failure arrives as an error, not as false
+ */
 ok: true
 }
 
@@ -112784,14 +113972,35 @@ export interface TrackingInstallDomainsListInput {
 }
 
 export interface TrackingInstallDomainsListOutput {
+/**
+ * Domains sending events that nobody registered — usually a staging host, a typo, or an install worth adding
+ */
 discovered: TrackingInstallDomainsListOutputItems[]
+/**
+ * Domains deliberately put on the install checklist, each with whether its script has been seen
+ */
 registered: TrackingInstallDomainsListOutputItems[]
+/**
+ * Length in days of the lookback window the `seen` and `lastSeen` figures are measured over
+ */
 windowDays: number
 }
 export interface TrackingInstallDomainsListOutputItems {
+/**
+ * Whether the tracking script actually sent an event from this domain inside the lookback window
+ */
 seen: boolean
+/**
+ * Normalised domain name the status is reported for
+ */
 domain: string
+/**
+ * ISO-8601 timestamp of the most recent event from this domain, or null if none arrived in the window
+ */
 lastSeen: (string | null)
+/**
+ * Whether the domain is on the install checklist on purpose, as opposed to merely observed sending events
+ */
 registered: boolean
 }
 
@@ -112803,6 +114012,9 @@ domain: string
 }
 
 export interface TrackingLinkDomainsCreateOutput {
+/**
+ * The domain as stored after normalisation, which may differ from what was submitted
+ */
 domain: string
 }
 
@@ -112814,6 +114026,9 @@ domain: string
 }
 
 export interface TrackingLinkDomainsDeleteOutput {
+/**
+ * Always true — the domain left the linking group; a failure arrives as an error, not as false
+ */
 ok: true
 }
 
@@ -112822,6 +114037,9 @@ export interface TrackingLinkDomainsListInput {
 }
 
 export interface TrackingLinkDomainsListOutput {
+/**
+ * Root domains in the linking group; the tracking script decorates links between any two of them so one visitor stays one visitor
+ */
 domains: string[]
 }
 
@@ -112841,22 +114059,70 @@ domain?: string
 }
 
 export interface TrackingLiveEventsListOutput {
+/**
+ * Pass back as `since` to fetch what arrived after this page. Null when there is nothing older to page into.
+ */
 cursor: (string | null)
+/**
+ * The page of events, newest first.
+ */
 events: {
+/**
+ * Stable identifier of this single event; unique within the product and safe to deduplicate on across polls.
+ */
 id: string
+/**
+ * When the event happened, as reported by the tracker (ISO 8601, UTC).
+ */
 ts: string
+/**
+ * Page address the event fired on, query string included. Free text from the customer site, so it can carry personal data.
+ */
 url: (string | null)
+/**
+ * Event name as sent by the site, e.g. 'pageview' or a custom conversion name.
+ */
 name: string
+/**
+ * Document title of that page at the time. Free text from the customer site, so it can carry personal data.
+ */
 title: (string | null)
+/**
+ * Site the event came from; null when the tracker could not determine one.
+ */
 domain: (string | null)
+/**
+ * Where this visit came from, as read off the landing URL and referrer. Every field is null when the visit carried nothing.
+ */
 source: {
+/**
+ * Address the visitor arrived from; null on a direct visit. Free text from the customer site, so it can carry personal data.
+ */
 referrer: (string | null)
+/**
+ * utm_medium of the landing URL, e.g. cpc; null when absent.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source of the landing URL, e.g. newsletter; null when absent.
+ */
 utmSource: (string | null)
+/**
+ * Which ad-network click id was present on the landing URL, e.g. 'gclid'. Null when the visit carried none.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign of the landing URL; null when absent.
+ */
 utmCampaign: (string | null)
 }
+/**
+ * Two-letter ISO 3166-1 alpha-2 country resolved from the request, e.g. DE; null when it could not be resolved.
+ */
 country: (string | null)
+/**
+ * Pseudonymous visitor id the person graph joins on. Null for a visitor who declined statistics consent or was never asked — those events arrive cookieless and carry no identifier at all.
+ */
 anonymousId: (string | null)
 }[]
 }
@@ -112869,18 +114135,52 @@ profileId: string
 }
 
 export interface TrackingProfilesDeleteOutput {
+/**
+ * Always true: the response only exists when the erasure ran. A failure arrives as an error, not as ok=false.
+ */
 ok: true
+/**
+ * What happened to the archived copy of the events. Postgres is erased synchronously; the archive is not, and this says so out loud.
+ */
 archive: {
+/**
+ * Plain-language reason the archived copy could not be deleted in the same breath — text meant to be quoted into a compliance record.
+ */
 note: string
+/**
+ * Always gap_flagged: the archived copy is known to still hold this person and the gap has been recorded rather than silently ignored.
+ */
 status: "gap_flagged"
 }
+/**
+ * How much was actually destroyed, by kind. Worth recording: it is the evidence that the erasure did something.
+ */
 deleted: {
+/**
+ * Tracked events removed, found through the anonymous ids this person browsed under.
+ */
 events: number
+/**
+ * Merge records removed — the history of this person having been joined with another.
+ */
 merges: number
+/**
+ * Profile rows removed: 1 in practice, and 0 only if the row vanished between the lookup and the delete.
+ */
 profile: number
+/**
+ * Emails, phones, anonymous ids and click ids removed for this person.
+ */
 identifiers: number
 }
+/**
+ * The person who was erased. Nothing else of them remains, so this is all there is left to name them by.
+ */
 profileId: string
+/**
+ * This erasure attempt. The completion event carries the same value under the same name, so a step recognises its own completion even when another workflow is erasing the same person at the same moment.
+ */
+requestId: string
 }
 
 export interface TrackingProfilesExportInput {
@@ -112891,52 +114191,172 @@ profileId: string
 }
 
 export interface TrackingProfilesExportOutput {
+/**
+ * The complete history, newest event first, capped at 50000 events — check `truncated` before treating it as complete.
+ */
 journey: {
+/**
+ * When the event happened, ISO 8601 UTC. The journey is ordered by this, newest first.
+ */
 ts: string
+/**
+ * Opaque handle for this one event, unique inside the product. Use it to deduplicate, not to sort — it carries no order.
+ */
 ref: string
+/**
+ * Full address of the page, query string included. Personal data — it can carry an email in a link. Null off-page.
+ */
 url: (string | null)
+/**
+ * What happened, as the tracking snippet named it: page_view, signup, purchase, or any custom name the product sends.
+ */
 name: string
+/**
+ * Custom properties the product attached to this event. Free-form: the keys are whatever the snippet sent, and they differ by event name.
+ */
 props: {
 [k: string]: unknown
 }
+/**
+ * Title of the page as the browser reported it. Null off-page.
+ */
 title: (string | null)
+/**
+ * Hostname the event was sent from. Null for an event with no page behind it, such as a server-side call.
+ */
 domain: (string | null)
+/**
+ * Campaign tags and ad click carried by this event, as they were on the URL at the time.
+ */
 source: {
+/**
+ * The ad click identifier on this URL, raw. Personal data: it resolves to one individual inside the ad network.
+ */
 clickId: (string | null)
+/**
+ * utm_term on the URL of this event — the keyword bought, on a paid-search arrival.
+ */
 utmTerm: (string | null)
+/**
+ * utm_medium on the URL of this event.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source on the URL of THIS event — the campaign at this moment, not the one that first acquired the person.
+ */
 utmSource: (string | null)
+/**
+ * utm_content on the URL of this event — which creative or link variant was clicked.
+ */
 utmContent: (string | null)
+/**
+ * Which ad network stamped the click id below: gclid for Google Ads, fbclid for Meta. Null on a non-ad arrival.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign on the URL of this event.
+ */
 utmCampaign: (string | null)
 }
+/**
+ * Two-letter ISO 3166-1 country the request came from, resolved from the IP at collection time. Null when it could not be resolved.
+ */
 country: (string | null)
+/**
+ * Where the person came from immediately before this event. Null on a direct arrival or off-page.
+ */
 referrer: (string | null)
+/**
+ * Handle for the browsing session this event belongs to; events sharing it happened in one sitting. Null for an event collected outside a session.
+ */
 sessionId: (string | null)
 }[]
+/**
+ * The person themselves: their handle, how far they have come, and when they were seen.
+ */
 profile: {
+/**
+ * How far the person has come: anonymous = only a browser behind them, identified = an email or phone is known, customer = they have paid at least once.
+ */
 status: ("anonymous" | "identified" | "customer")
+/**
+ * When this product first created the profile row, ISO 8601 UTC. Later than firstSeenAt when events were backfilled.
+ */
 createdAt: string
+/**
+ * Stable handle for this person inside the product. Pass it to any other people step; it survives identity merges.
+ */
 profileId: string
+/**
+ * Timestamp of their most recent event, ISO 8601 UTC — the freshness of everything else here.
+ */
 lastSeenAt: string
+/**
+ * Timestamp of the earliest event on record for this person, ISO 8601 UTC.
+ */
 firstSeenAt: string
 }
+/**
+ * Everything known about who this person is: the addresses they have been identified by, the ad clicks they arrived by, and the sites they were seen on. Every part of it is a list, and none of the lists names a primary.
+ */
 signals: {
+/**
+ * Every email this person has ever been identified by. Stably ordered for display and diffing — the position of an address says NOTHING about which one to contact, and this toolkit holds no primary. Usually one entry; a person who signed up twice has several.
+ */
 emails: string[]
+/**
+ * Every phone number this person has been identified by. Stably ordered for display and diffing only, with no primary among them.
+ */
 phones: string[]
+/**
+ * Distinct hostnames this person browsed, taken from their events — not an identifier type, just where they were.
+ */
 domains: string[]
+/**
+ * Every ad click this person arrived by, stably ordered and with no primary among them. Personal data: a click id resolves to one individual inside the ad network.
+ */
 clickIds: {
+/**
+ * Which ad network the click came from — gclid for Google Ads, fbclid for Meta. Open set.
+ */
 type: string
+/**
+ * The click identifier itself, raw, as the network stamped it on the landing URL.
+ */
 value: string
 }[]
 }
+/**
+ * True when the history hit the 50000-event cap and older events were left out. False means this export is everything held.
+ */
 truncated: boolean
+/**
+ * When this export was produced, ISO 8601 UTC — the as-of date to put on a subject-access response.
+ */
 exportedAt: string
+/**
+ * First touch: the campaign that brought this person in, frozen at their earliest event and never overwritten by later visits. Null for a person with no events at all.
+ */
 acquisition: ({
+/**
+ * Channel of that same first visit (utm_medium): cpc, email, social, and so on. Null when untagged.
+ */
 utmMedium: (string | null)
+/**
+ * Where the person came from on their very first visit — the utm_source of their earliest event. Null when they arrived with no campaign tags.
+ */
 utmSource: (string | null)
+/**
+ * Which ad network stamped the click that brought them in — gclid for Google Ads, fbclid for Meta. Null for a non-ad arrival. Open set: new networks appear without a release here.
+ */
 clickIdType: (string | null)
+/**
+ * When that first visit happened, ISO 8601 UTC. This is the timestamp of the earliest event, not when the profile row was written.
+ */
 firstSeenAt: string
+/**
+ * Campaign of that same first visit (utm_campaign). Null when untagged.
+ */
 utmCampaign: (string | null)
 } | null)
 }
@@ -112951,78 +114371,228 @@ profileId: string
  */
 journeyLimit?: number
 /**
- * Opaque cursor to page further back through the journey
+ * Continue paging back through the journey: pass the cursor the previous page returned. Omit to start at the most recent event.
  */
 journeyCursor?: string
 }
 
 export interface TrackingProfilesGetOutput {
+/**
+ * Lifetime value of this person, per currency. Null when revenue tracking is not in use for the product.
+ */
 ltv: ({
+/**
+ * One row per currency this person has paid in. Empty for someone who never paid; there is no cross-currency total, because converting would need a rate this toolkit does not hold.
+ */
 entries: {
+/**
+ * ISO 4217 code the amounts beside it are denominated in, e.g. EUR. One entry per code the person ever paid in.
+ */
 currency: string
+/**
+ * What the business actually kept: gross minus refunded, in minor units. This is the number to rank customers by.
+ */
 netMinor: number
+/**
+ * Everything the person was ever charged, in minor units (1250 = 12.50 EUR). Refunds are not subtracted here.
+ */
 grossMinor: number
+/**
+ * Their most recent payment in this currency, ISO 8601 UTC — how live the relationship is.
+ */
 lastPaymentAt: (string | null)
+/**
+ * How much of the gross went back to them, in minor units. Zero for a person who never had a refund.
+ */
 refundedMinor: number
+/**
+ * When this person first paid in this currency, ISO 8601 UTC. Null when the totals were computed without a dated payment.
+ */
 firstPaymentAt: (string | null)
 }[]
+/**
+ * The person these totals belong to — the same handle as profile.profileId.
+ */
 profileId: string
+/**
+ * When these totals were last recomputed, ISO 8601 UTC. Null when they have never been computed.
+ */
 computedAt: (string | null)
 } | null)
+/**
+ * What this person did, newest first, one page at a time. Use the export step instead when the whole history is wanted in one go.
+ */
 journey: {
+/**
+ * Pass back as `journeyCursor` to page further back in time. Null once the journey is exhausted.
+ */
 cursor: (string | null)
+/**
+ * This page of the journey, newest event first.
+ */
 events: {
+/**
+ * When the event happened, ISO 8601 UTC. The journey is ordered by this, newest first.
+ */
 ts: string
+/**
+ * Opaque handle for this one event, unique inside the product. Use it to deduplicate, not to sort — it carries no order.
+ */
 ref: string
+/**
+ * Full address of the page, query string included. Personal data — it can carry an email in a link. Null off-page.
+ */
 url: (string | null)
+/**
+ * What happened, as the tracking snippet named it: page_view, signup, purchase, or any custom name the product sends.
+ */
 name: string
+/**
+ * Custom properties the product attached to this event. Free-form: the keys are whatever the snippet sent, and they differ by event name.
+ */
 props: {
 [k: string]: unknown
 }
+/**
+ * Title of the page as the browser reported it. Null off-page.
+ */
 title: (string | null)
+/**
+ * Hostname the event was sent from. Null for an event with no page behind it, such as a server-side call.
+ */
 domain: (string | null)
+/**
+ * Campaign tags and ad click carried by this event, as they were on the URL at the time.
+ */
 source: {
+/**
+ * The ad click identifier on this URL, raw. Personal data: it resolves to one individual inside the ad network.
+ */
 clickId: (string | null)
+/**
+ * utm_term on the URL of this event — the keyword bought, on a paid-search arrival.
+ */
 utmTerm: (string | null)
+/**
+ * utm_medium on the URL of this event.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source on the URL of THIS event — the campaign at this moment, not the one that first acquired the person.
+ */
 utmSource: (string | null)
+/**
+ * utm_content on the URL of this event — which creative or link variant was clicked.
+ */
 utmContent: (string | null)
+/**
+ * Which ad network stamped the click id below: gclid for Google Ads, fbclid for Meta. Null on a non-ad arrival.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign on the URL of this event.
+ */
 utmCampaign: (string | null)
 }
+/**
+ * Two-letter ISO 3166-1 country the request came from, resolved from the IP at collection time. Null when it could not be resolved.
+ */
 country: (string | null)
+/**
+ * Where the person came from immediately before this event. Null on a direct arrival or off-page.
+ */
 referrer: (string | null)
+/**
+ * Handle for the browsing session this event belongs to; events sharing it happened in one sitting. Null for an event collected outside a session.
+ */
 sessionId: (string | null)
 }[]
 }
+/**
+ * The person themselves: their handle, how far they have come, and when they were seen.
+ */
 profile: {
+/**
+ * How far the person has come: anonymous = only a browser behind them, identified = an email or phone is known, customer = they have paid at least once.
+ */
 status: ("anonymous" | "identified" | "customer")
+/**
+ * When this product first created the profile row, ISO 8601 UTC. Later than firstSeenAt when events were backfilled.
+ */
 createdAt: string
+/**
+ * Stable handle for this person inside the product. Pass it to any other people step; it survives identity merges.
+ */
 profileId: string
+/**
+ * Timestamp of their most recent event, ISO 8601 UTC — the freshness of everything else here.
+ */
 lastSeenAt: string
+/**
+ * Timestamp of the earliest event on record for this person, ISO 8601 UTC.
+ */
 firstSeenAt: string
 }
+/**
+ * Everything known about who this person is: the addresses they have been identified by, the ad clicks they arrived by, and the sites they were seen on. Every part of it is a list, and none of the lists names a primary.
+ */
 signals: {
+/**
+ * Every email this person has ever been identified by. Stably ordered for display and diffing — the position of an address says NOTHING about which one to contact, and this toolkit holds no primary. Usually one entry; a person who signed up twice has several.
+ */
 emails: string[]
+/**
+ * Every phone number this person has been identified by. Stably ordered for display and diffing only, with no primary among them.
+ */
 phones: string[]
+/**
+ * Distinct hostnames this person browsed, taken from their events — not an identifier type, just where they were.
+ */
 domains: string[]
+/**
+ * Every ad click this person arrived by, stably ordered and with no primary among them. Personal data: a click id resolves to one individual inside the ad network.
+ */
 clickIds: {
+/**
+ * Which ad network the click came from — gclid for Google Ads, fbclid for Meta. Open set.
+ */
 type: string
+/**
+ * The click identifier itself, raw, as the network stamped it on the landing URL.
+ */
 value: string
 }[]
 }
+/**
+ * First touch: the campaign that brought this person in, frozen at their earliest event and never overwritten by later visits. Null for a person with no events at all.
+ */
 acquisition: ({
+/**
+ * Channel of that same first visit (utm_medium): cpc, email, social, and so on. Null when untagged.
+ */
 utmMedium: (string | null)
+/**
+ * Where the person came from on their very first visit — the utm_source of their earliest event. Null when they arrived with no campaign tags.
+ */
 utmSource: (string | null)
+/**
+ * Which ad network stamped the click that brought them in — gclid for Google Ads, fbclid for Meta. Null for a non-ad arrival. Open set: new networks appear without a release here.
+ */
 clickIdType: (string | null)
+/**
+ * When that first visit happened, ISO 8601 UTC. This is the timestamp of the earliest event, not when the profile row was written.
+ */
 firstSeenAt: string
+/**
+ * Campaign of that same first visit (utm_campaign). Null when untagged.
+ */
 utmCampaign: (string | null)
 } | null)
 }
 
 export interface TrackingProfilesListInput {
 /**
- * Exact email to find (case-insensitive), or a prefix when emailMatch=prefix
+ * Email to search people by — the whole address by default, or its beginning when emailMatch is prefix. Omit to search across everyone.
  */
 email?: string
 /**
@@ -113030,132 +114600,363 @@ email?: string
  */
 limit?: number
 /**
- * Opaque pagination cursor from a previous response
+ * Continue a previous page: pass the cursor that page returned. Omit to start from the most recently seen person.
  */
 cursor?: string
 /**
- * Filter by profile status
+ * Keep only people at this stage — anonymous, identified or customer. Omit to get all three.
  */
 status?: ("anonymous" | "identified" | "customer")
 /**
- * How to match the email filter
+ * How the email filter is matched: exact (default) compares the whole address case-insensitively, prefix matches everyone whose address starts with what you typed.
  */
 emailMatch?: ("exact" | "prefix")
 }
 
 export interface TrackingProfilesListOutput {
+/**
+ * Pass this back as `cursor` to fetch the next page. Null on the last page — that null is how a loop knows to stop.
+ */
 cursor: (string | null)
+/**
+ * The page of people, most recently seen first. Shorter than the requested limit on the last page.
+ */
 profiles: {
+/**
+ * Every email this person has been identified by. Stably ordered for display, with no primary among them — position 0 is not the address to contact.
+ */
 emails: string[]
+/**
+ * How far this person has come: anonymous = only a browser, identified = an email or phone is known, customer = they have paid.
+ */
 status: ("anonymous" | "identified" | "customer")
+/**
+ * Stable handle for this person. Feed it to a get, export or erase step.
+ */
 profileId: string
+/**
+ * Timestamp of their most recent event, ISO 8601 UTC. The page is ordered by this, newest first.
+ */
 lastSeenAt: string
+/**
+ * First touch: the campaign that brought this person in, frozen at their earliest event and never overwritten by later visits. Null for a person with no events at all.
+ */
 acquisition: ({
+/**
+ * Channel of that same first visit (utm_medium): cpc, email, social, and so on. Null when untagged.
+ */
 utmMedium: (string | null)
+/**
+ * Where the person came from on their very first visit — the utm_source of their earliest event. Null when they arrived with no campaign tags.
+ */
 utmSource: (string | null)
+/**
+ * Which ad network stamped the click that brought them in — gclid for Google Ads, fbclid for Meta. Null for a non-ad arrival. Open set: new networks appear without a release here.
+ */
 clickIdType: (string | null)
+/**
+ * When that first visit happened, ISO 8601 UTC. This is the timestamp of the earliest event, not when the profile row was written.
+ */
 firstSeenAt: string
+/**
+ * Campaign of that same first visit (utm_campaign). Null when untagged.
+ */
 utmCampaign: (string | null)
 } | null)
+/**
+ * Timestamp of their earliest event, ISO 8601 UTC.
+ */
 firstSeenAt: string
 }[]
 }
 
 export interface TrackingReportsAttributedJourneyInput {
+/**
+ * Show only journey events at or before this instant (ISO). Omit for the whole history.
+ */
 to?: string
+/**
+ * Show only journey events at or after this instant (ISO). Omit for the whole history.
+ */
 from?: string
+/**
+ * Attribution model to explain the decision under; re-reads the same history, so switching it is free (default 'last_click').
+ */
 model?: ("last_click" | "first_click")
 /**
  * The profile id (uuid)
  */
 profileId: string
+/**
+ * How far back before the conversion a touchpoint may be credited, in days (default 30).
+ */
 lookbackDays?: number
 }
 
 export interface TrackingReportsAttributedJourneyOutput {
+/**
+ * What this person actually did, in order.
+ */
 journey: {
+/**
+ * Every tracked event for this person inside the requested window, oldest first.
+ */
 events: {
+/**
+ * When the event happened (ISO 8601, UTC). Events are ordered oldest first.
+ */
 ts: string
+/**
+ * Handle for this event within the journey; `decisions[].winnerRef` points back at one of these to name the winning touchpoint.
+ */
 ref: string
+/**
+ * Page address the event fired on. Free text from the customer site, so it can carry personal data.
+ */
 url: (string | null)
+/**
+ * Event name as sent by the site, e.g. 'pageview' or a custom conversion name.
+ */
 name: string
+/**
+ * Custom properties the site attached to this event. Shape is the customer's, so it can carry anything, personal data included.
+ */
 props: {
 [k: string]: unknown
 }
+/**
+ * Document title of that page. Free text from the customer site, so it can carry personal data.
+ */
 title: (string | null)
+/**
+ * Site the event came from; null when the tracker could not determine one.
+ */
 domain: (string | null)
+/**
+ * Where this event's visit came from, as read off the landing URL. Every field is null when the visit carried nothing.
+ */
 source: {
+/**
+ * The click id value itself. Identifies one ad click by this person, so treat it as personal data.
+ */
 clickId: (string | null)
+/**
+ * utm_term of the landing URL, the paid keyword; null when absent.
+ */
 utmTerm: (string | null)
+/**
+ * utm_medium of the landing URL; null when absent.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source of the landing URL; null when absent.
+ */
 utmSource: (string | null)
+/**
+ * utm_content of the landing URL, the creative variant; null when absent.
+ */
 utmContent: (string | null)
+/**
+ * Which ad-network click id was present, e.g. 'gclid'; null when the visit carried none.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign of the landing URL; null when absent.
+ */
 utmCampaign: (string | null)
 }
+/**
+ * Two-letter ISO 3166-1 alpha-2 country resolved from the request, e.g. DE; null when it could not be resolved.
+ */
 country: (string | null)
+/**
+ * Address the visitor arrived from; null on a direct visit. Free text from the customer site, so it can carry personal data.
+ */
 referrer: (string | null)
+/**
+ * Visit this event belongs to; events sharing one happened in the same sitting. Null when no session could be established.
+ */
 sessionId: (string | null)
 }[]
 }
-decisions: {
+/**
+ * Holds at most one entry: the decision for this person's originating conversion, present only when that conversion falls inside the requested window. Kept as a list for callers that already read it; `originatingDecision` is the same value at a bindable path.
+ */
+decisions: TrackingReportsAttributedJourneyOutputItems[]
+/**
+ * The person this journey belongs to, echoed back from the request.
+ */
+profileId: string
+/**
+ * The attribution decision for this person's originating conversion — the same value as `decisions[0]`, at a path a workflow can bind. Null means the decision is not in THIS window, not that the person never converted: a conversion before `from` or after `to` is excluded here while still being their originating one. Widen the window to see it.
+ */
+originatingDecision: (TrackingReportsAttributedJourneyOutputItems | null)
+}
+export interface TrackingReportsAttributedJourneyOutputItems {
+/**
+ * Attribution model the winner was picked under, echoed back from the request.
+ */
 model: ("last_click" | "first_click")
+/**
+ * Why this touchpoint won, or why nothing did, in a sentence a person can read.
+ */
 reason: string
+/**
+ * Revenue of that conversion, one row per currency.
+ */
 revenue: {
+/**
+ * ISO 4217 code the amounts below are denominated in, e.g. EUR.
+ */
 currency: string
+/**
+ * `grossMinor` minus `refundedMinor`, in minor units of `currency`. This is the figure to report.
+ */
 netMinor: number
+/**
+ * Billed amount before refunds, in minor units of `currency` (cents for EUR).
+ */
 grossMinor: number
+/**
+ * Amount refunded out of `grossMinor`, in minor units of `currency`.
+ */
 refundedMinor: number
 }[]
+/**
+ * `journey.events[].ref` of the touchpoint that won the credit. Null when nothing inside the window qualified.
+ */
 winnerRef: (string | null)
+/**
+ * When the conversion this decision explains happened (ISO 8601, UTC).
+ */
 conversionTs: string
+/**
+ * How far back before `conversionTs` a touchpoint was allowed to be credited, in days; echoed back.
+ */
 lookbackDays: number
+/**
+ * The winning touchpoint spelled out, so a reader need not resolve `winnerRef`. Null exactly when `winnerRef` is null.
+ */
 winningTouchpoint: ({
+/**
+ * When the winning touchpoint happened (ISO 8601, UTC).
+ */
 ts: string
+/**
+ * Channel the winning touchpoint belongs to.
+ */
 channel: ("paid" | "organic" | "direct" | "email")
+/**
+ * utm_medium of the winning touchpoint; null when it carried none.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source of the winning touchpoint; null when it carried none.
+ */
 utmSource: (string | null)
+/**
+ * Campaign id carried by our own `_lt_campaign` landing-URL parameter; null when the visit carried none.
+ */
+ltCampaign?: (string | null)
+/**
+ * Ad-network click id present on the winning touchpoint, e.g. 'gclid'; null when it carried none.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign of the winning touchpoint; null when it carried none.
+ */
 utmCampaign: (string | null)
 } | null)
-}[]
-profileId: string
 }
 
 export interface TrackingReportsEventVolumeInput {
-to: string
-from: string
+/**
+ * End of the range to count, inclusive (ISO 8601). Optional — defaults to the moment of the call.
+ */
+to?: string
+/**
+ * Start of the range to count, inclusive (ISO 8601). Optional — defaults to 30 days back, the start of that UTC day.
+ */
+from?: string
+/**
+ * Count only this site. Omit to count every site the product sends from.
+ */
 domain?: string
 }
 
 export interface TrackingReportsEventVolumeOutput {
+/**
+ * End of the range the figures cover, echoed back (ISO 8601, UTC).
+ */
 to: string
+/**
+ * Start of the range the figures cover, echoed back (ISO 8601, UTC).
+ */
 from: string
+/**
+ * Site the figures were restricted to; null when every site of the product is included.
+ */
 domain: (string | null)
+/**
+ * When this report was computed (ISO 8601, UTC).
+ */
 computedAt: string
+/**
+ * How COMPLETE the two headline figures above are. Contains no metric of its own — never present a field of it as a headline number and never add it to anything. consentGrantedEvents + cookielessEvents + noBannerEvents = totalEvents.
+ */
 dataQuality: {
+/**
+ * Fraction of `totalEvents` (0..1) that came from sites running no consent banner, where nobody was ever asked.
+ */
 noBannerShare: number
+/**
+ * Events from sites with no consent banner. Kept apart from `cookielessEvents` on purpose: nobody refused here, nobody was asked.
+ */
 noBannerEvents: number
+/**
+ * How many UTC days the range spans; each one re-counts a returning declining visitor.
+ */
 utcDaysInRange: number
+/**
+ * Fraction of `totalEvents` (0..1) that came from visitors who declined statistics consent.
+ */
 cookielessShare: number
+/**
+ * Events from visitors who declined; no cookie was written and no identifier sent.
+ */
 cookielessEvents: number
+/**
+ * Events carrying an anonymous id. A different cut that overlaps the three consent buckets — it is not the complement of `cookielessEvents` and must never be added to it.
+ */
 identifiedEvents: number
+/**
+ * True when `visitorsDeduplicatedPerUtcDay` over-counts for this range: the range spans more than one UTC day and there is declining traffic in it.
+ */
 visitorsOverstated: boolean
+/**
+ * Events from visitors who granted statistics consent.
+ */
 consentGrantedEvents: number
 }
+/**
+ * How many events arrived in the range, across every consent state.
+ */
 totalEvents: number
+/**
+ * How many PEOPLE those events came from: one COUNT DISTINCT over consenting visitors (by anonymous id) and declining visitors (by a daily key destroyed each UTC midnight) at once. Over a range longer than one UTC day this is an OVER-count of the declining half — read `dataQuality.visitorsOverstated` before reporting it.
+ */
 visitorsDeduplicatedPerUtcDay: number
 }
 
 export interface TrackingReportsRevenueBySourceInput {
 /**
- * Cohort window end (ISO)
+ * Cohort window end (ISO). Optional — defaults to the moment of the call.
  */
-to: string
+to?: string
 /**
- * Cohort window start (ISO); selects conversions by subscription start
+ * Cohort window start (ISO); selects conversions by subscription start. Optional — defaults to 30 days back, the start of that UTC day.
  */
-from: string
+from?: string
 /**
  * Attribution model
  */
@@ -113171,54 +114972,150 @@ lookbackDays?: number
 }
 
 export interface TrackingReportsRevenueBySourceOutput {
+/**
+ * End of the cohort window the figures cover, echoed back (ISO 8601, UTC).
+ */
 to: string
+/**
+ * Start of the cohort window the figures cover, echoed back (ISO 8601, UTC).
+ */
 from: string
+/**
+ * Attribution model the credit was assigned under, echoed back. Pass the same value to `tracking_reports_source_people` to drill into a row.
+ */
 model: ("last_click" | "first_click")
+/**
+ * Site touchpoints were restricted to; null when every site of the product was considered.
+ */
 domain: (string | null)
+/**
+ * Every channel plus `unattributed`. This is the whole window, not the attributed part of it.
+ */
 totals: {
+/**
+ * Revenue over every channel plus `unattributed`, one row per currency.
+ */
 revenue: TrackingReportsRevenueBySourceOutputItems[]
+/**
+ * Distinct paying people over every channel plus `unattributed`.
+ */
 customers: number
 }
+/**
+ * One row per channel that earned revenue in the window. Channels with none are omitted.
+ */
 channels: {
+/**
+ * Which acquisition channel this row aggregates.
+ */
 channel: ("paid" | "organic" | "direct" | "email")
+/**
+ * Revenue credited to this channel, one row per currency, ordered by currency code. Currencies are never summed, so there is no single figure here: a product trading in two currencies has two rows and both must be reported.
+ */
 revenue: TrackingReportsRevenueBySourceOutputItems[]
+/**
+ * Distinct paying people credited to this channel.
+ */
 customers: number
+/**
+ * The channel split by UTM combination. Each row is a drill-down target for `tracking_reports_source_people`.
+ */
 utmBreakdown: {
+/**
+ * Revenue credited to this UTM combination, one row per currency.
+ */
 revenue: TrackingReportsRevenueBySourceOutputItems[]
+/**
+ * Distinct paying people credited to this UTM combination.
+ */
 customers: number
+/**
+ * utm_medium of this row; null when the visit carried none.
+ */
 utmMedium: (string | null)
+/**
+ * utm_source of this row; null when the visit carried none.
+ */
 utmSource: (string | null)
+/**
+ * Ad-network click id present on the visit, e.g. 'gclid'; null when it carried none.
+ */
 clickIdType: (string | null)
+/**
+ * utm_campaign of this row; null when the visit carried none.
+ */
 utmCampaign: (string | null)
 }[]
 }[]
+/**
+ * Fraction of paying people (0..1) a touchpoint could be found for: attributed customers over `totals.customers`. Count-based, never revenue-weighted.
+ */
 matchRate: number
+/**
+ * When this report was computed (ISO 8601, UTC).
+ */
 computedAt: string
+/**
+ * How far back before a conversion a touchpoint was allowed to be credited, in days; echoed back.
+ */
 lookbackDays: number
+/**
+ * Revenue that reached no channel — kept as its own row so the channel rows are never quietly inflated to cover it.
+ */
 unattributed: {
+/**
+ * Revenue no touchpoint could be credited for, one row per currency.
+ */
 revenue: TrackingReportsRevenueBySourceOutputItems[]
+/**
+ * Distinct paying people no touchpoint could be credited for.
+ */
 customers: number
 }
 }
 export interface TrackingReportsRevenueBySourceOutputItems {
+/**
+ * ISO 4217 code the amounts below are denominated in, e.g. EUR.
+ */
 currency: string
+/**
+ * `grossMinor` minus `refundedMinor`, in minor units of `currency`. This is the figure to report.
+ */
 netMinor: number
+/**
+ * Billed amount before refunds, in minor units of `currency` (cents for EUR).
+ */
 grossMinor: number
+/**
+ * Amount refunded out of `grossMinor`, in minor units of `currency`.
+ */
 refundedMinor: number
 }
 
 export interface TrackingReportsSourcePeopleInput {
-to: string
-from: string
+/**
+ * Cohort window end (ISO); must match the report this row came from. Optional — defaults to the moment of the call.
+ */
+to?: string
+/**
+ * Cohort window start (ISO); must match the report this row came from. Optional — defaults to 30 days back, the start of that UTC day.
+ */
+from?: string
 /**
  * People per page (default 50, max 200)
  */
 limit?: number
+/**
+ * Attribution model to credit the touchpoint under; must match the report this row came from (default 'last_click').
+ */
 model?: ("last_click" | "first_click")
 /**
  * Opaque keyset cursor from a previous page
  */
 cursor?: string
+/**
+ * Only consider touchpoints on this domain; must match the report this row came from. Omit for no restriction.
+ */
 domain?: string
 /**
  * Channel to drill into
@@ -113228,27 +115125,72 @@ channel: ("paid" | "organic" | "direct" | "email")
  * Comma-separated dimension names (utmSource,utmMedium,utmCampaign,clickIdType) that must be IS NULL
  */
 utmNulls?: string
+/**
+ * utm_medium of the breakdown row to drill into. Omit for no filter; to match the IS-NULL row, list it in utmNulls instead.
+ */
 utmMedium?: string
+/**
+ * utm_source of the breakdown row to drill into. Omit for no filter; to match the IS-NULL row, list it in utmNulls instead.
+ */
 utmSource?: string
 /**
  * Native click-id type of the breakdown row to drill into (e.g. 'gclid'). Tri-state: omit for no filter (all click ids), pass a value to match it, or list 'clickIdType' in utmNulls to match the IS-NULL row.
  */
 clickIdType?: string
+/**
+ * utm_campaign of the breakdown row to drill into. Omit for no filter; to match the IS-NULL row, list it in utmNulls instead.
+ */
 utmCampaign?: string
+/**
+ * How far back before a conversion a touchpoint may be credited, in days; must match the report this row came from (default 30).
+ */
 lookbackDays?: number
 }
 
 export interface TrackingReportsSourcePeopleOutput {
+/**
+ * Pass back as `cursor` for the next page. Null on the last page.
+ */
 cursor: (string | null)
+/**
+ * The page of people behind the requested row, ordered by the keyset the cursor walks.
+ */
 people: {
+/**
+ * Where this person stands in their subscription lifecycle, e.g. active or churned.
+ */
 status: string
+/**
+ * Identifier of this person; pass it to `tracking_reports_attributed_journey` to see why they were credited here.
+ */
 profileId: string
+/**
+ * Most recent tracked activity for this person (ISO 8601, UTC); null when none was recorded.
+ */
 lastSeenAt: (string | null)
+/**
+ * Earliest tracked activity for this person (ISO 8601, UTC); null when none was recorded.
+ */
 firstSeenAt: (string | null)
+/**
+ * Lifetime revenue credited to this person under the requested model, one row per currency.
+ */
 attributedRevenue: {
+/**
+ * ISO 4217 code the amounts below are denominated in, e.g. EUR.
+ */
 currency: string
+/**
+ * `grossMinor` minus `refundedMinor`, in minor units of `currency`. This is the figure to report.
+ */
 netMinor: number
+/**
+ * Billed amount before refunds, in minor units of `currency` (cents for EUR).
+ */
 grossMinor: number
+/**
+ * Amount refunded out of `grossMinor`, in minor units of `currency`.
+ */
 refundedMinor: number
 }[]
 }[]
@@ -113259,9 +115201,21 @@ export interface TrackingSnippetsGetInput {
 }
 
 export interface TrackingSnippetsGetOutput {
+/**
+ * Tracking host the snippet sends to — the customer-facing domain events and the bundle are served from.
+ */
 host: string
+/**
+ * The tag to paste into every page, verbatim, before </head>. Includes the consent-aware bootstrap; install it unconditionally rather than behind a consent gate.
+ */
 snippet: string
+/**
+ * Absolute URL of the tracker bundle the snippet loads; already points at this product's own tracking host.
+ */
 scriptUrl: string
+/**
+ * The same tag stripped to the bare script element, for tag managers and CMS fields that reject anything else. Behaves identically; use it only when the full snippet will not fit.
+ */
 minimalSnippet: string
 }
 
@@ -113277,13 +115231,75 @@ type: ("server" | "publishable")
 }
 
 export interface UsersApikeysCreateOutput {
+/**
+ * Id of the key. Pass it to users_apikeys_revoke.
+ */
 id: string
+/**
+ * The full secret key, shown ONCE. Store it now — it is never returned again, and a lost key is replaced by minting a new one.
+ */
 key: string
+/**
+ * The label a human gave this key — which backend or environment holds it.
+ */
+name: string
+/**
+ * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+ */
+type: ("server" | "publishable")
+/**
+ * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+ */
+value: (string | null)
+/**
+ * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+ */
+prefix: string
+/**
+ * When the key was issued (ISO 8601).
+ */
+createdAt: string
+/**
+ * When the key was revoked (ISO 8601). Null while it still works.
+ */
+revokedAt: (string | null)
+}
+
+export interface UsersApikeysGetInput {
+/**
+ * Id of the key to read — the `id` from users_apikeys_list.
+ */
+id: string
+}
+
+export interface UsersApikeysGetOutput {
+/**
+ * Id of the key. Pass it to users_apikeys_revoke.
+ */
+id: string
+/**
+ * The label a human gave this key — which backend or environment holds it.
+ */
 name: string
+/**
+ * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+ */
 type: ("server" | "publishable")
+/**
+ * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+ */
 value: (string | null)
+/**
+ * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+ */
 prefix: string
+/**
+ * When the key was issued (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the key was revoked (ISO 8601). Null while it still works.
+ */
 revokedAt: (string | null)
 }
 
@@ -113293,12 +115309,33 @@ export interface UsersApikeysListInput {
 
 export interface UsersApikeysListOutput {
 keys: {
+/**
+ * Id of the key. Pass it to users_apikeys_revoke.
+ */
 id: string
+/**
+ * The label a human gave this key — which backend or environment holds it.
+ */
 name: string
+/**
+ * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+ */
 type: ("server" | "publishable")
+/**
+ * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+ */
 value: (string | null)
+/**
+ * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+ */
 prefix: string
+/**
+ * When the key was issued (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the key was revoked (ISO 8601). Null while it still works.
+ */
 revokedAt: (string | null)
 }[]
 }
@@ -113311,7 +115348,13 @@ id: string
 }
 
 export interface UsersApikeysRevokeOutput {
+/**
+ * Id of the key that was revoked.
+ */
 id: string
+/**
+ * Always true — revocation is immediate and final.
+ */
 revoked: true
 }
 
@@ -113347,21 +115390,60 @@ targetType?: string
 }
 
 export interface UsersAuditListOutput {
+/**
+ * The page of audit events, newest first.
+ */
 events: {
+/**
+ * Id of this audit row.
+ */
 id: string
+/**
+ * IP the action came from. Null when it was not an HTTP action.
+ */
 ip: (string | null)
+/**
+ * What happened, as a dotted name — `user.created`, `passkey.deleted`, `email_change.override_applied`.
+ */
 action: string
+/**
+ * Id of the actor. Null for a system action.
+ */
 actorId: (string | null)
+/**
+ * Action-specific detail — the reason text, counts, whatever the action recorded.
+ */
 metadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the row the action was about. Null when there was none.
+ */
 targetId: (string | null)
+/**
+ * Who acted: `operator` (a human or agent on the management plane), `end_user`, or `system`.
+ */
 actorType: ("operator" | "system" | "end_user")
+/**
+ * When the action happened (ISO 8601).
+ */
 createdAt: string
+/**
+ * Product the audited action happened in.
+ */
 productId: string
+/**
+ * User agent the action came from. Null when none was sent.
+ */
 userAgent: (string | null)
+/**
+ * What kind of row the action was about — `user` or `product`. Null when it was about nothing in particular.
+ */
 targetType: (string | null)
 }[]
+/**
+ * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+ */
 nextCursor: (string | null)
 }
 
@@ -114344,12 +116426,33 @@ userId: string
 }
 
 export interface UsersFactorsListOutput {
+/**
+ * Every second factor this user has — types and status only, never material.
+ */
 factors: {
+/**
+ * Kind of second factor: `totp` or `backup_codes`. No key material is ever returned.
+ */
 type: ("totp" | "backup_codes" | "webauthn")
+/**
+ * Whether this factor is enrolled and usable, or still pending verification.
+ */
 status: ("unverified" | "verified")
+/**
+ * When the factor was enrolled (ISO 8601).
+ */
 createdAt: string
+/**
+ * `backup_codes` only: how many of the batch are still unspent. Null for any other factor type.
+ */
 remaining: (number | null)
+/**
+ * When the factor was last used to sign in (ISO 8601). Null if it never was.
+ */
 lastUsedAt: (string | null)
+/**
+ * When the user first proved the factor works (ISO 8601). Null while it is unverified.
+ */
 verifiedAt: (string | null)
 }[]
 }
@@ -114366,7 +116469,13 @@ userId: string
 }
 
 export interface UsersFactorsResetOutput {
+/**
+ * Id of the scheduled reset. The same value arrives on `users/mfa.reset-settled`, which is what finishes this step.
+ */
 requestId: string
+/**
+ * When the removal happens, if nobody aborts it first (ISO 8601). The delay is this product's, not a fixed one.
+ */
 scheduledFor: string
 }
 
@@ -114662,6 +116771,52 @@ signInFailureBaseline: (number | null)
 }
 }
 
+export interface UsersPasskeysGetInput {
+/**
+ * The end user the credential belongs to.
+ */
+userId: string
+/**
+ * Which credential to read — the `id` from `users_passkeys_list`.
+ */
+passkeyId: string
+}
+
+export interface UsersPasskeysGetOutput {
+/**
+ * Id of the credential. Pass it to users_passkeys_revoke.
+ */
+id: string
+/**
+ * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+ */
+name: (string | null)
+/**
+ * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+ */
+aaguid: (string | null)
+/**
+ * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+ */
+backedUp: boolean
+/**
+ * When the credential was registered (ISO 8601).
+ */
+createdAt: string
+/**
+ * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+ */
+signCount: number
+/**
+ * When it last signed in (ISO 8601). Null when it never has.
+ */
+lastUsedAt: (string | null)
+/**
+ * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+ */
+transports: string[]
+}
+
 export interface UsersPasskeysListInput {
 /**
  * The end user whose passkeys to list.
@@ -114670,14 +116825,41 @@ userId: string
 }
 
 export interface UsersPasskeysListOutput {
+/**
+ * The credentials this user has registered, newest first. Empty when they have none.
+ */
 passkeys: {
+/**
+ * Id of the credential. Pass it to users_passkeys_revoke.
+ */
 id: string
+/**
+ * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+ */
 name: (string | null)
+/**
+ * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+ */
 aaguid: (string | null)
+/**
+ * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+ */
 backedUp: boolean
+/**
+ * When the credential was registered (ISO 8601).
+ */
 createdAt: string
+/**
+ * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+ */
 signCount: number
+/**
+ * When it last signed in (ISO 8601). Null when it never has.
+ */
 lastUsedAt: (string | null)
+/**
+ * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+ */
 transports: string[]
 }[]
 }
@@ -114702,9 +116884,18 @@ export interface UsersPasskeysRevokeOutput {
  * Present when the revoke was refused — today, only because it was the last way in.
  */
 error: ({
+/**
+ * Why it was refused. Today only `passkey_last_way_in`.
+ */
 code: string
+/**
+ * The refusal in a sentence, safe to show a human.
+ */
 message: string
 } | null)
+/**
+ * `deleted` when the credential is gone, `failed` when the revoke was refused.
+ */
 status: ("deleted" | "failed")
 }
 
@@ -114716,7 +116907,13 @@ sessionId: string
 }
 
 export interface UsersSessionsGetOutput {
+/**
+ * Id of this session. Pass it to users_sessions_revoke.
+ */
 id: string
+/**
+ * IP the session was opened from. Null when it was not recorded.
+ */
 ip: (string | null)
 /**
  * `aal2` only if a verified second factor completed.
@@ -114726,18 +116923,45 @@ aal: ("aal1" | "aal2")
  * The factors this session was established with.
  */
 amr: string[]
+/**
+ * Whether the session is still usable, expired, or revoked.
+ */
 status: ("active" | "revoked")
+/**
+ * The end user this session belongs to.
+ */
 userId: string
+/**
+ * When the session was opened (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the current token stops working unless refreshed (ISO 8601).
+ */
 expiresAt: string
+/**
+ * When the session was revoked (ISO 8601). Null while it is live.
+ */
 revokedAt: (string | null)
+/**
+ * User agent the session was opened from. Null when none was sent.
+ */
 userAgent: (string | null)
+/**
+ * Why the session ended, when it was revoked — e.g. `signout`, `ban`, `mfa_reset`. Null while it is live. The vocabulary is additive, so it is not an enum.
+ */
 revokedReason: (string | null)
 /**
  * The operator behind an impersonated session, or null for an ordinary one.
  */
 impersonatedBy: (string | null)
+/**
+ * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+ */
 lastRefreshedAt: (string | null)
+/**
+ * When the session ends no matter how often it refreshes (ISO 8601).
+ */
 absoluteExpiresAt: string
 }
 
@@ -114777,16 +117001,49 @@ userId: string
 }
 
 export interface UsersSessionsListOutput {
+/**
+ * The sessions matching the filter, newest first.
+ */
 sessions: {
+/**
+ * Id of this session. Pass it to users_sessions_revoke.
+ */
 id: string
+/**
+ * IP the session was opened from. Null when it was not recorded.
+ */
 ip: (string | null)
+/**
+ * Whether the session is still usable, expired, or revoked.
+ */
 status: ("active" | "revoked")
+/**
+ * The end user this session belongs to.
+ */
 userId: string
+/**
+ * When the session was opened (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the current token stops working unless refreshed (ISO 8601).
+ */
 expiresAt: string
+/**
+ * When the session was revoked (ISO 8601). Null while it is live.
+ */
 revokedAt: (string | null)
+/**
+ * User agent the session was opened from. Null when none was sent.
+ */
 userAgent: (string | null)
+/**
+ * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+ */
 lastRefreshedAt: (string | null)
+/**
+ * When the session ends no matter how often it refreshes (ISO 8601).
+ */
 absoluteExpiresAt: string
 }[]
 }
@@ -114803,6 +117060,9 @@ sessionId?: string
 }
 
 export interface UsersSessionsRevokeOutput {
+/**
+ * How many sessions were revoked. Zero when there was nothing live to revoke.
+ */
 revoked: number
 }
 
@@ -114929,37 +117189,126 @@ userId: string
 }
 
 export interface UsersUsersBanOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersBanOutputPublicMetadata
-unsafeMetadata: UsersUsersBanOutputPublicMetadata
-privateMetadata: UsersUsersBanOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersBanOutputPublicMetadata {
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersUsersCreateInput {
 /**
@@ -115062,37 +117411,126 @@ export interface UsersUsersCreateInputPublicMetadata1 {
 }
 
 export interface UsersUsersCreateOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersCreateOutputPublicMetadata
-unsafeMetadata: UsersUsersCreateOutputPublicMetadata
-privateMetadata: UsersUsersCreateOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersCreateOutputPublicMetadata {
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersUsersDeleteInput {
 /**
@@ -115102,37 +117540,126 @@ userId: string
 }
 
 export interface UsersUsersDeleteOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersDeleteOutputPublicMetadata
-unsafeMetadata: UsersUsersDeleteOutputPublicMetadata
-privateMetadata: UsersUsersDeleteOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersDeleteOutputPublicMetadata {
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersUsersExportInput {
 /**
@@ -115160,40 +117687,129 @@ includeDeleted?: boolean
 export interface UsersUsersExportOutput {
 count: number
 users: {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersExportOutputPublicMetadata
-unsafeMetadata: UsersUsersExportOutputPublicMetadata
-privateMetadata: UsersUsersExportOutputPublicMetadata
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
+[k: string]: unknown
+}
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
 emailChangeLockedUntil: (string | null)
 }[]
 exportedAt: string
 nextCursor: (string | null)
 }
-export interface UsersUsersExportOutputPublicMetadata {
-[k: string]: unknown
-}
 
 export interface UsersUsersGetInput {
 /**
@@ -115203,37 +117819,126 @@ userId: string
 }
 
 export interface UsersUsersGetOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersGetOutputPublicMetadata
-unsafeMetadata: UsersUsersGetOutputPublicMetadata
-privateMetadata: UsersUsersGetOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersGetOutputPublicMetadata {
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersUsersImportInput {
 /**
@@ -115246,15 +117951,42 @@ users: [unknown, ...(unknown)[]]
 }
 
 export interface UsersUsersImportOutput {
+/**
+ * How many rows could not be imported at all.
+ */
 failed: number
+/**
+ * How many users were created.
+ */
 created: number
+/**
+ * One row per submitted row, in the order you sent them.
+ */
 results: {
+/**
+ * Zero-based index of the row in the `users` array you sent.
+ */
 row: number
+/**
+ * Why it was skipped, or what went wrong. Null for a created row.
+ */
 reason: (string | null)
+/**
+ * What happened to this row.
+ */
 status: ("created" | "skipped" | "failed")
+/**
+ * The created user's id. Null for skipped and failed rows.
+ */
 userId: (string | null)
 }[]
+/**
+ * How many rows were passed over — an address already in the directory, typically.
+ */
 skipped: number
+/**
+ * How many rows you submitted.
+ */
 requested: number
 }
 
@@ -115282,9 +118014,21 @@ privateMetadata?: {
 }
 
 export interface UsersUsersInviteOutput {
+/**
+ * False when the re-invite cooldown or the mail toolkit refused the send. The invite is still live.
+ */
 mailed: boolean
+/**
+ * The invited user, created immediately and listed straight away — they simply cannot sign in until they accept.
+ */
 userId: string
+/**
+ * False when this address had already been invited; the same user is returned.
+ */
 created: boolean
+/**
+ * When the invite link stops working (ISO 8601).
+ */
 expiresAt: string
 }
 
@@ -115320,40 +118064,135 @@ includeWaitlisted?: boolean
 }
 
 export interface UsersUsersListOutput {
+/**
+ * The page of users, newest first.
+ */
 users: {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersListOutputPublicMetadata
-unsafeMetadata: UsersUsersListOutputPublicMetadata
-privateMetadata: UsersUsersListOutputPublicMetadata
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
+[k: string]: unknown
+}
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
 emailChangeLockedUntil: (string | null)
 }[]
+/**
+ * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+ */
 nextCursor: (string | null)
 }
-export interface UsersUsersListOutputPublicMetadata {
-[k: string]: unknown
-}
 
 export interface UsersUsersSetPrimaryIdentifierInput {
 /**
@@ -115371,7 +118210,13 @@ userId: string
 }
 
 export interface UsersUsersSetPrimaryIdentifierOutput {
+/**
+ * Id of the scheduled change. It appears in the audit rows and in the abort link mailed to the old address.
+ */
 requestId: string
+/**
+ * When the swap becomes applicable, if nobody aborts it first (ISO 8601). The delay is this product's `emailChange.overrideDelayHours`, 72 by default.
+ */
 scheduledFor: string
 }
 
@@ -115383,37 +118228,126 @@ userId: string
 }
 
 export interface UsersUsersUnbanOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersUnbanOutputPublicMetadata
-unsafeMetadata: UsersUsersUnbanOutputPublicMetadata
-privateMetadata: UsersUsersUnbanOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersUnbanOutputPublicMetadata {
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersUsersUpdateInput {
 /**
@@ -115463,37 +118397,126 @@ export interface UsersUsersUpdateInputPublicMetadata1 {
 }
 
 export interface UsersUsersUpdateOutput {
+/**
+ * Id of this end user. Pass it to any users_users_* tool.
+ */
 id: string
+/**
+ * The user's display name. Null when nobody set one.
+ */
 name: (string | null)
+/**
+ * When the user was banned (ISO 8601). Null while they are not banned.
+ */
 bannedAt: (string | null)
+/**
+ * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+ */
 erasedAt: (string | null)
+/**
+ * URL of the user's avatar. Null when there is none.
+ */
 imageUrl: (string | null)
+/**
+ * Whether this is a test fixture — excluded from metering and from the default listing.
+ */
 testUser: boolean
+/**
+ * When the user was created (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the user was soft-deleted (ISO 8601). Null while the account is live.
+ */
 deletedAt: (string | null)
+/**
+ * Product this user belongs to. Never an input — it comes from the calling identity.
+ */
 productId: string
+/**
+ * When the user was last changed (ISO 8601).
+ */
 updatedAt: string
+/**
+ * Whether this user is still on the waitlist and cannot sign in yet.
+ */
 waitlisted: boolean
+/**
+ * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+ */
 identifiers: {
+/**
+ * Id of this identifier row.
+ */
 id: string
+/**
+ * What kind of identifier this is. Today always `email`.
+ */
 type: "email"
+/**
+ * The address as the user typed it, for display.
+ */
 value: string
+/**
+ * Whether this is the identifier the user signs in with and is contacted at.
+ */
 isPrimary: boolean
+/**
+ * When this address was verified (ISO 8601). Null while it never was.
+ */
 verifiedAt: (string | null)
+/**
+ * The address lowercased and NFC-normalised — what uniqueness is checked against.
+ */
 valueCanonical: string
+/**
+ * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+ */
 verificationStatus: ("unverified" | "verified" | "expired")
 }[]
+/**
+ * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+ */
 lockedUntil: (string | null)
+/**
+ * When the user last signed in (ISO 8601). Null if they never have.
+ */
 lastSignInAt: (string | null)
+/**
+ * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+ */
+primaryEmail: (string | null)
+/**
+ * Whether the user must set a new password at their next sign-in.
+ */
 requiresReset: boolean
-publicMetadata: UsersUsersUpdateOutputPublicMetadata
-unsafeMetadata: UsersUsersUpdateOutputPublicMetadata
-privateMetadata: UsersUsersUpdateOutputPublicMetadata
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersUpdateOutputPublicMetadata {
+/**
+ * Metadata the end user may write themselves. Treat it as untrusted.
+ */
+unsafeMetadata: {
+[k: string]: unknown
+}
+/**
+ * Metadata for the management plane only. Never reaches the end user or a token.
+ */
+privateMetadata: {
 [k: string]: unknown
 }
+/**
+ * Id of the primary identifier row. Null when there is no primary identifier.
+ */
+primaryIdentifierId: (string | null)
+/**
+ * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+ */
+emailChangeLockedUntil: (string | null)
+}
 
 export interface UsersWaitlistFunnelInput {
 
@@ -115508,6 +118531,64 @@ registered: number
 unconfirmed: number
 }
 
+export interface UsersWaitlistGetInput {
+/**
+ * The waitlisted user to read — the `userId` from `users_waitlist_list`.
+ */
+userId: string
+}
+
+export interface UsersWaitlistGetOutput {
+/**
+ * Where in the funnel this entry is: `pending`, `invited`, `registered` or `withdrawn`.
+ */
+status: ("pending" | "invited" | "registered" | "withdrawn")
+/**
+ * The waitlisted user. Every users_users_* tool takes this id.
+ */
+userId: string
+/**
+ * When the entry joined the waitlist (ISO 8601).
+ */
+createdAt: string
+/**
+ * When the invite was sent (ISO 8601). Null while the entry is pending.
+ */
+invitedAt: (string | null)
+/**
+ * The email address that signed up.
+ */
+identifier: string
+/**
+ * Where the signup came from — the campaign, referrer and landing page recorded at the time.
+ */
+attribution: {
+[k: string]: unknown
+}
+/**
+ * When the address confirmed a double opt-in (ISO 8601). Null when it never did.
+ */
+confirmedAt: (string | null)
+/**
+ * When the address asked to be taken off the list (ISO 8601). Null when it did not.
+ */
+withdrawnAt: (string | null)
+/**
+ * What was recorded to show this address consented: when, from where, and under which wording.
+ */
+consentProof: {
+[k: string]: unknown
+}
+/**
+ * When the invitee finished signing up (ISO 8601). Null until they do.
+ */
+registeredAt: (string | null)
+/**
+ * Id of the live invite token. Null while the entry has not been invited.
+ */
+inviteTokenId: (string | null)
+}
+
 export interface UsersWaitlistImportInput {
 /**
  * The legacy signups to import, at most 500 per call — batch client-side beyond that.
@@ -115673,15 +118754,42 @@ unsafeMetadata?: {
 }
 
 export interface UsersWaitlistImportOutput {
+/**
+ * How many could not be imported at all.
+ */
 failed: number
+/**
+ * One row per submitted row, in the order you sent them.
+ */
 results: {
+/**
+ * Zero-based index of the row in the array you sent.
+ */
 row: number
+/**
+ * Why it was skipped, or what went wrong. Null for an imported row.
+ */
 reason: (string | null)
+/**
+ * What happened to this row.
+ */
 status: ("imported" | "skipped" | "failed")
+/**
+ * The waitlisted user this row created. Null for skipped and failed rows.
+ */
 userId: (string | null)
 }[]
+/**
+ * How many were already on the list or otherwise passed over.
+ */
 skipped: number
+/**
+ * How many became waitlist entries.
+ */
 imported: number
+/**
+ * How many rows you submitted.
+ */
 requested: number
 }
 
@@ -115696,12 +118804,30 @@ userIds: [string, ...(string)[]]
 }
 
 export interface UsersWaitlistInviteOutput {
+/**
+ * How many of the requested users were invited.
+ */
 invited: number
+/**
+ * One row per user you asked for, in the order you sent them.
+ */
 results: {
+/**
+ * Why this user was skipped. Null for an invited row.
+ */
 reason: (("suppressed" | "not_found" | "already_registered") | null)
+/**
+ * Whether this user was invited or passed over.
+ */
 status: ("invited" | "skipped")
+/**
+ * The user this row is about.
+ */
 userId: string
 }[]
+/**
+ * How many were passed over — see each row's `reason`.
+ */
 skipped: number
 }
 
@@ -115725,23 +118851,62 @@ confirmed?: boolean
 }
 
 export interface UsersWaitlistListOutput {
+/**
+ * The page of waitlist entries, newest first.
+ */
 entries: {
+/**
+ * Where in the funnel this entry is: `pending`, `invited`, `registered` or `withdrawn`.
+ */
 status: ("pending" | "invited" | "registered" | "withdrawn")
+/**
+ * The waitlisted user. Every users_users_* tool takes this id.
+ */
 userId: string
+/**
+ * When the entry joined the waitlist (ISO 8601).
+ */
 createdAt: string
+/**
+ * When the invite was sent (ISO 8601). Null while the entry is pending.
+ */
 invitedAt: (string | null)
+/**
+ * The email address that signed up.
+ */
 identifier: string
+/**
+ * Where the signup came from — the campaign, referrer and landing page recorded at the time.
+ */
 attribution: {
 [k: string]: unknown
 }
+/**
+ * When the address confirmed a double opt-in (ISO 8601). Null when it never did.
+ */
 confirmedAt: (string | null)
+/**
+ * When the address asked to be taken off the list (ISO 8601). Null when it did not.
+ */
 withdrawnAt: (string | null)
+/**
+ * What was recorded to show this address consented: when, from where, and under which wording.
+ */
 consentProof: {
 [k: string]: unknown
 }
+/**
+ * When the invitee finished signing up (ISO 8601). Null until they do.
+ */
 registeredAt: (string | null)
+/**
+ * Id of the live invite token. Null while the entry has not been invited.
+ */
 inviteTokenId: (string | null)
 }[]
+/**
+ * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+ */
 nextCursor: (string | null)
 }
 
@@ -115896,194 +119061,6 @@ description: (string | null)
 secretPrefix: string
 }
 
-export interface WaitlistConfigGetInput {
-
-}
-
-export type WaitlistConfigGetOutput = ({
-createdAt: string
-policyUrl: (string | null)
-productId: string
-updatedAt: string
-senderName: (string | null)
-consentText: string
-policyLabel: (string | null)
-siteBaseUrl: (string | null)
-senderDomain: (string | null)
-inviteSubject: (string | null)
-policyVersion: string
-inviteTemplate: (string | null)
-} | null)
-
-export interface WaitlistConfigUpsertInput {
-/**
- * Policy link URL (http/https/mailto). Rendered as a structured link in the form. Null to clear.
- */
-policyUrl?: (string | null)
-/**
- * Controller display name shown as the invite From name and in the default email body (A7§64 controller identity). Stored as-is. Null to clear (falls back to a generic sender name).
- */
-senderName?: (string | null)
-/**
- * Plain-text consent statement shown at signup. May contain a {policy} placeholder marking the policy link. Stored as-is (no HTML sanitization).
- */
-consentText: string
-/**
- * Visible text for the policy link. Falls back to the URL itself if absent.
- */
-policyLabel?: (string | null)
-/**
- * Per-product public base URL of the tenant site; invite (/signup) and opt-out (/withdraw) links are built from it. http/https only, path allowed, trailing slash stripped. Stored as-is (DP-013); not content-verified. Null to clear.
- */
-siteBaseUrl?: (string | null)
-/**
- * Sender domain for invite emails (bare hostname). Verification happens at send time, not here. Null to clear.
- */
-senderDomain?: (string | null)
-/**
- * Invite email subject line. Plain text, stored as-is; CR/LF stripped at send time. Null to clear (falls back to a default subject).
- */
-inviteSubject?: (string | null)
-/**
- * Policy version label, controller-owned free string. Stored as-is, not validated for monotonicity.
- */
-policyVersion: string
-/**
- * Invite email template ({{vars}}). Stored as-is; rendered/validated at send time. Null to clear.
- */
-inviteTemplate?: (string | null)
-}
-
-export interface WaitlistConfigUpsertOutput {
-createdAt: string
-policyUrl: (string | null)
-productId: string
-updatedAt: string
-senderName: (string | null)
-consentText: string
-policyLabel: (string | null)
-siteBaseUrl: (string | null)
-senderDomain: (string | null)
-inviteSubject: (string | null)
-policyVersion: string
-inviteTemplate: (string | null)
-}
-
-export interface WaitlistEmbedGetInput {
-
-}
-
-export interface WaitlistEmbedGetOutput {
-product_id: string
-script_tag: string
-public_edge_url: string
-}
-
-export interface WaitlistInvitesSendInput {
-/**
- * Resend even when a live invite token already exists (mints a fresh token).
- */
-force?: boolean
-/**
- * Explicit recipient emails (e.g. from waitlist_signups_list). Combined with filter if both given.
- */
-emails?: string[]
-/**
- * Selection filter over signups; resolved server-side with pagination.
- */
-filter?: {
-/**
- * Prefix match on email (case-insensitive).
- */
-q?: string
-/**
- * Select signups by status (single value or array).
- */
-status?: (("pending" | "invited" | "registered") | ("pending" | "invited" | "registered")[])
-}
-}
-
-export interface WaitlistInvitesSendOutput {
-sent: {
-email: string
-emailId: string
-}[]
-failed: {
-email: string
-reason: ("quota_exceeded" | "reputation_throttled" | "send_failed")
-}[]
-skipped: {
-email: string
-reason: ("suppressed" | "already_invited" | "already_registered")
-}[]
-}
-
-export interface WaitlistSignupsEraseInput {
-/**
- * Email address to erase (GDPR Art.17) within the current product. Normalized (trimmed + lowercased) server-side. The operation is idempotent.
- */
-email: string
-}
-
-export interface WaitlistSignupsEraseOutput {
-suppressed: boolean
-deletedTokens: number
-deletedSignups: number
-reducedConsents: number
-}
-
-export interface WaitlistSignupsFunnelInput {
-/**
- * Time window. "7d"/"30d"/"90d" = trailing N days ending now; "all" = all time. Default "30d".
- */
-period?: ("7d" | "30d" | "90d" | "all")
-}
-
-export interface WaitlistSignupsFunnelOutput {
-to: string
-from: (string | null)
-period: string
-signup: number
-invited: number
-registered: number
-non_monotonic: boolean
-}
-
-export interface WaitlistSignupsListInput {
-/**
- * Prefix search on email (case-insensitive). Returns signups whose email starts with this value. Audited as PII access (DP-009).
- */
-q?: string
-/**
- * Page size, 1–200. Default 50.
- */
-limit?: number
-/**
- * Sort by created_at. newest = most recent first. Default newest.
- */
-order?: ("newest" | "oldest")
-/**
- * Keyset cursor from a previous response next_cursor. Omit to start from the beginning.
- */
-cursor?: string
-/**
- * Fields to include per row. Default ["status","created_at"]; id is always included. email and ip_hash are PII and audited when requested.
- */
-fields?: ("status" | "created_at" | "source" | "country" | "email" | "ip_hash")[]
-/**
- * Filter by status. A single value or an array. Omit to return all statuses.
- */
-status?: (("pending" | "invited" | "registered") | ("pending" | "invited" | "registered")[])
-}
-
-export interface WaitlistSignupsListOutput {
-items: {
-[k: string]: unknown
-}[]
-has_more: boolean
-next_cursor: (string | null)
-}
-
 export interface WorkflowCapListInput {
 
 }