@tappify/extension-sdk 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,1016 @@
+export { u as useTap } from './context-Dt6xh_5t.cjs';
+export { T as TAP_ERROR_CODES, a as TapError, b as TapErrorCode, c as TapServerError } from './errors-COsBh7kd.cjs';
+import { T as Tap, a as TapFilters, b as TapSize, c as TapHostEvents, d as TapQuery, e as TapResult, f as TapProcedureName, g as TapProcedureInput, h as TapProcedureOutput, i as TapSingletonName, j as TapSingletonDocument } from './types-DrpQSv_2.cjs';
+export { A as ActionId, k as ActionInput, P as PromptId, l as PromptInput, m as TapActionMap, n as TapActionRun, o as TapApp, p as TapChangeKey, q as TapChatCard, r as TapCollection, s as TapComparisonSide, t as TapConfirmOptions, u as TapCrashIssue, v as TapCrashesResult, w as TapCredentialValues, x as TapCredentials, y as TapDateRange, z as TapFormatters, B as TapHostEventMap, C as TapInternals, D as TapKeyword, E as TapKeywordsResult, F as TapListing, G as TapListingResult, H as TapPageProps, I as TapPath, J as TapPlatform, K as TapPlatformFilter, L as TapProcedureMap, M as TapProcedures, N as TapProjectResult, O as TapPromptMap, Q as TapRelease, R as TapRevenueResult, S as TapReview, U as TapReviewsResult, V as TapRowActionProps, W as TapSeriesMetric, X as TapSeriesPoint, Y as TapSeriesResult, Z as TapSettings, _ as TapSettingsProps, $ as TapSettingsValues, a0 as TapSingleton, a1 as TapStorage, a2 as TapStorageMap, a3 as TapTabProps, a4 as TapTableColumn, a5 as TapTelemetryEvents, a6 as TapToastTone, a7 as TapToolMap, a8 as TapWebhookMap, a9 as TapWidgetProps, aa as TelemetryEvent, ab as ToolId, ac as ToolInput, ad as WebhookName, ae as WebhookPayload } from './types-DrpQSv_2.cjs';
+import { ClassValue as ClassValue$1 } from 'clsx';
+import { ButtonHTMLAttributes, ReactElement, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes } from 'react';
+import { J as JsonSchema } from './constants-DJ_KgZpN.cjs';
+export { D as DataQueryKind, H as HostEventName, a as HostPage, S as ScopeKey, b as SlotId } from './constants-DJ_KgZpN.cjs';
+
+/**
+ * Returns the install token, the signed-in teammate, the workspace id, the
+ * granted scopes and `can(scope)`.
+ *
+ * @remarks
+ * Re-renders the component when the host rotates the install token, and when the
+ * signed-in teammate's role arrives after the mount. `scopes` and `can` report the
+ * grant the mount was built with. Throws `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { TapEmptyState, useTapAuth } from '@tappify/extension-sdk';
+ *
+ * function RevenuePanel() {
+ *   const auth = useTapAuth();
+ *   if (!auth.can('revenue:read')) {
+ *     return <TapEmptyState title="Revenue is not shared with this extension" />;
+ *   }
+ *   return <span>Signed in as {auth.user.id}</span>;
+ * }
+ * ```
+ */
+declare function useTapAuth(): Tap['auth'];
+/**
+ * Returns the project the mount renders in, with its apps, releases and tracked
+ * keywords.
+ *
+ * @remarks
+ * Re-renders when the host loads or reloads the project. Throws
+ * `TAP_OUTSIDE_HOST` outside a mount. An extension installed on the workspace
+ * rather than a project still renders inside one project at a time.
+ *
+ * @example
+ * ```tsx
+ * import { useTapProject } from '@tappify/extension-sdk';
+ *
+ * function Platforms() {
+ *   const project = useTapProject();
+ *   return <span>{project.name} ships to {project.platforms.join(' and ')}</span>;
+ * }
+ * ```
+ */
+declare function useTapProject(): Tap['project'];
+/**
+ * Returns the date range, platform and country the owner's filter bar is set to.
+ *
+ * @remarks
+ * Re-renders on every filter change, which is how a surface follows the owner's
+ * picker. Pass `range` into a `series`, `reviews`, `crashes` or `revenue` query
+ * yourself; the host adds only the country to a data read, while a procedure call
+ * carries all three. Throws `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { useTapFilters, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Downloads() {
+ *   const filters = useTapFilters();
+ *   const downloads = useTapQuery({
+ *     kind: 'series',
+ *     metric: 'downloads',
+ *     range: filters.range,
+ *   });
+ *   return <span>{downloads.data?.points.length ?? 0} days</span>;
+ * }
+ * ```
+ */
+declare function useTapFilters(): TapFilters;
+/**
+ * Returns the mode the host is drawing in, as `{ mode: 'light' | 'dark' }`.
+ *
+ * @remarks
+ * Re-renders when the owner switches theme. The host's CSS variables already
+ * follow the theme, so reach for this only where a component has to branch in
+ * code rather than restyle, such as a chart's series colours. Throws
+ * `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { useTapTheme } from '@tappify/extension-sdk';
+ *
+ * function SeriesLine() {
+ *   const theme = useTapTheme();
+ *   const stroke = theme.mode === 'dark' ? '#a5b4fc' : '#4f46e5';
+ *   return <svg><line x1="0" y1="0" x2="40" y2="10" stroke={stroke} /></svg>;
+ * }
+ * ```
+ */
+declare function useTapTheme(): Tap['theme'];
+/**
+ * Returns how much room the mount has: `slot`, `panel` or `page`.
+ *
+ * @remarks
+ * Expanding a widget mounts a second copy of the component in the panel rather
+ * than resizing the one in the slot, so the change this hook reports is the
+ * panel's own Widen and Narrow toggle moving between `panel` and `page`. Size
+ * against the mount with a container query where CSS can do the work; this hook is
+ * for the cases that need different markup. Throws `TAP_OUTSIDE_HOST` outside a
+ * mount.
+ *
+ * @example
+ * ```tsx
+ * import { TapTable, useTapSize } from '@tappify/extension-sdk';
+ *
+ * function Keywords({ rows }: { rows: { term: string }[] }) {
+ *   const size = useTapSize();
+ *   const shown = size === 'slot' ? rows.slice(0, 3) : rows;
+ *   return (
+ *     <TapTable
+ *       columns={[{ key: 'term', label: 'Term' }]}
+ *       rows={shown}
+ *       rowKey={row => row.term}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useTapSize(): TapSize;
+/**
+ * Returns the route of the extension's own page: the page id, the whole sub-path,
+ * and one key per segment.
+ *
+ * @remarks
+ * The host builds `pageId`, `path` and then `0`, `1` and so on, one per segment of
+ * the sub-path. Only a page entry is routed, so this is empty for a widget, a tab,
+ * a row action and a settings panel. Re-renders when the owner navigates inside the
+ * page. Throws `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { useTapParams } from '@tappify/extension-sdk';
+ *
+ * function FunnelDetail() {
+ *   const params = useTapParams();
+ *   const funnelId = params['1'];
+ *   return <span>{funnelId ?? params.path}</span>;
+ * }
+ * ```
+ */
+declare function useTapParams(): Record<string, string>;
+/**
+ * Returns what the surface handed the mount: the payload Expand carried in, or
+ * the row behind a row action.
+ *
+ * @remarks
+ * Re-renders when the host hands the mount a new context. A row action reads the
+ * row from its own `row` prop as well; this hook is the same value for a
+ * component further down the tree. Throws `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { useTapContext } from '@tappify/extension-sdk';
+ *
+ * function ContextNote() {
+ *   const context = useTapContext();
+ *   const reviewId = context.reviewId;
+ *   return <span>{typeof reviewId === 'string' ? reviewId : 'No review'}</span>;
+ * }
+ * ```
+ */
+declare function useTapContext(): Record<string, unknown>;
+/**
+ * Returns one value from the in-memory store every mount of the install shares,
+ * with a setter for it.
+ *
+ * @remarks
+ * The value is `undefined` until something sets it, and setting it re-renders
+ * every mount reading the same key, including a sibling widget and the expand
+ * panel. The store lives in the browser session: it is not persisted, not shared
+ * between teammates or tabs, and never reaches Tappify or your server — use
+ * `useTapStorage` for a value that has to come back tomorrow. Throws
+ * `TAP_OUTSIDE_HOST` outside a mount.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, useTapState } from '@tappify/extension-sdk';
+ *
+ * function StepPicker() {
+ *   const [step, setStep] = useTapState<string>('selectedStep');
+ *   return (
+ *     <TapButton onClick={() => setStep('install')}>
+ *       {step ?? 'Pick a step'}
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function useTapState<T>(key: string): [T | undefined, (value: T) => void];
+
+/** The third argument of `useTapQuery` and `useTapServer`. */
+interface TapQueryOptions {
+    /** Holds the call back while this is `false`. Defaults to `true`. */
+    enabled?: boolean;
+    /** Tappify events that mark this result stale and refetch it when they arrive. */
+    invalidateOn?: (keyof TapHostEvents)[];
+}
+/** What `useTapQuery` and `useTapServer` return. */
+interface TapQueryResult<T> {
+    /**
+     * `undefined` until the first answer for this key arrives. A later call that
+     * fails leaves the last answer in place and only sets `error`, so branch on
+     * `error` to detect a failure, never on `data`.
+     */
+    data: T | undefined;
+    error: Error | null;
+    /** `true` only while the first answer for this key is in flight. */
+    isLoading: boolean;
+    /** Asks again now, whether or not the cached answer has gone stale. */
+    refetch(): void;
+}
+/** What `useTapStorage` returns: a read of the document, plus the two writes. */
+interface TapStorageResult<T> extends TapQueryResult<T | null> {
+    /** Replaces the whole document. */
+    save(document: T): Promise<void>;
+    /** Merges the fields in and resolves to the merged document. */
+    patch(partial: Partial<T>): Promise<T>;
+}
+/**
+ * Builds the cache key `useTapQuery` reads a Tappify data query under.
+ *
+ * @remarks
+ * The key carries the install, the query and the filters behind it, so two mounts
+ * asking for the same numbers share one request. Call it only to reach the query
+ * cache directly; the hooks build their own keys.
+ *
+ * @example
+ * ```ts
+ * import { dataQueryKey } from '@tappify/extension-sdk';
+ *
+ * const key = dataQueryKey('ins_test', { kind: 'keywords' }, {
+ *   range: { from: '2026-09-01', to: '2026-09-08' },
+ *   platform: 'all',
+ *   country: 'all',
+ * });
+ * ```
+ */
+declare function dataQueryKey(installId: string, query: TapQuery, filters: TapFilters): unknown[];
+/**
+ * Builds the cache key `useTapServer` reads one procedure call under.
+ *
+ * @remarks
+ * The input and the filters are part of the key, so the same procedure called
+ * with different input caches separately. Call it only to reach the query cache
+ * directly.
+ *
+ * @example
+ * ```ts
+ * import { procedureQueryKey } from '@tappify/extension-sdk';
+ *
+ * const key = procedureQueryKey('ins_test', 'getSummary', { days: 7 }, {
+ *   range: { from: '2026-09-01', to: '2026-09-08' },
+ *   platform: 'all',
+ *   country: 'all',
+ * });
+ * ```
+ */
+declare function procedureQueryKey(installId: string, name: string, input: unknown, filters: TapFilters): unknown[];
+/**
+ * Builds the cache key `useTapStorage` reads one collection's document under.
+ *
+ * @remarks
+ * The filters are not part of the key, because a stored document does not depend
+ * on them. Call it only to reach the query cache directly.
+ *
+ * @example
+ * ```ts
+ * import { storageQueryKey } from '@tappify/extension-sdk';
+ *
+ * const key = storageQueryKey('ins_test', 'preferences');
+ * ```
+ */
+declare function storageQueryKey(installId: string, collection: string): unknown[];
+/**
+ * Builds the key prefix every cached answer of one install sits under.
+ *
+ * @remarks
+ * This is the prefix `tap.invalidate()` with no name invalidates.
+ *
+ * @example
+ * ```ts
+ * import { installPrefix } from '@tappify/extension-sdk';
+ *
+ * const prefix = installPrefix('ins_test');
+ * ```
+ */
+declare function installPrefix(installId: string): unknown[];
+/**
+ * Builds the key prefix every cached call of one procedure sits under, whatever
+ * its input.
+ *
+ * @remarks
+ * This is the prefix `tap.invalidate(name)` invalidates.
+ *
+ * @example
+ * ```ts
+ * import { procedurePrefix } from '@tappify/extension-sdk';
+ *
+ * const prefix = procedurePrefix('ins_test', 'getSummary');
+ * ```
+ */
+declare function procedurePrefix(installId: string, name: string): unknown[];
+/**
+ * Reads one query's worth of the owner's Tappify data, cached per install, query
+ * and filter bar.
+ *
+ * @remarks
+ * Each kind needs its own scope — `project` needs `projects:read`, `series` needs
+ * `analytics:read`, `keywords` and `listing` need `store.metadata:read`, and
+ * `reviews`, `crashes` and `revenue` need their own. A kind the install has not
+ * granted comes back as a `TapError` with code `TAP_SCOPE_MISSING` in `error`. An
+ * answer stays fresh for 30 seconds and a failed read is not retried, so
+ * `refetch` is yours to call. The host adds only the country filter to the read:
+ * pass `range` into a `series`, `reviews`, `crashes` or `revenue` query yourself,
+ * and `platform` into a `series` query, which is the only kind that takes one.
+ * Throws `TAP_NO_QUERY_CLIENT` when no Tappify mount provides the query client.
+ *
+ * @example
+ * ```tsx
+ * import { TapStat, useTapFilters, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Downloads() {
+ *   const filters = useTapFilters();
+ *   const downloads = useTapQuery(
+ *     { kind: 'series', metric: 'downloads', range: filters.range },
+ *     { invalidateOn: ['release.shipped'] },
+ *   );
+ *   const points = downloads.data?.points ?? [];
+ *   const total = points.reduce((sum, point) => sum + point.value, 0);
+ *   return <TapStat label="Downloads" value={total} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import { TapTable, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Keywords() {
+ *   const keywords = useTapQuery({ kind: 'keywords' });
+ *   return (
+ *     <TapTable
+ *       columns={[
+ *         { key: 'term', label: 'Term' },
+ *         { key: 'position', label: 'Rank', align: 'end' },
+ *       ]}
+ *       rows={keywords.data?.keywords ?? []}
+ *       rowKey={keyword => keyword.id}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useTapQuery<Q extends TapQuery>(query: Q, options?: TapQueryOptions): TapQueryResult<TapResult<Q>>;
+/**
+ * Calls one procedure on your own server, cached per install, name, input and
+ * filter bar.
+ *
+ * @remarks
+ * The name and the input are narrowed by the `TapProcedureMap` augmentation
+ * `tappify extension types` writes, so a procedure the manifest does not declare
+ * does not compile; at runtime a name the host has no route for throws
+ * `TAP_UNKNOWN_PROCEDURE`. The call carries the whole filter bar for you. An
+ * answer stays fresh for 30 seconds and a failure is not retried; an error your
+ * server threw arrives as a `TapServerError` with your own `code`. Throws
+ * `TAP_NO_QUERY_CLIENT` when no Tappify mount provides the query client.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapErrorState, useTapFilters, useTapServer } from '@tappify/extension-sdk';
+ *
+ * function Summary() {
+ *   const filters = useTapFilters();
+ *   const summary = useTapServer(
+ *     'getSummary',
+ *     { days: 7, platform: filters.platform },
+ *     { invalidateOn: ['settings.changed'] },
+ *   );
+ *   if (summary.error !== null) {
+ *     return <TapErrorState title="The summary did not load" description={summary.error.message} />;
+ *   }
+ *   return <TapButton loading={summary.isLoading} onClick={summary.refetch}>Refresh</TapButton>;
+ * }
+ * ```
+ */
+declare function useTapServer<N extends TapProcedureName>(name: N, input: TapProcedureInput<N>, options?: TapQueryOptions): TapQueryResult<TapProcedureOutput<N>>;
+/**
+ * Reads and writes the one document a singleton storage collection holds.
+ *
+ * @remarks
+ * The argument is a collection name from the `TapStorageMap` augmentation
+ * `tappify extension types` writes, and the collection has to be declared with
+ * `"singleton": true`; an id-keyed collection throws `TAP_UNKNOWN_COLLECTION`,
+ * with the `tap.storage.<name>.list()` path in the message. `data` is `undefined`
+ * while the first read is in flight and `null` until the document is first
+ * written. Every storage call needs the `storage:write` scope, reads included, and
+ * rejects with `TAP_SCOPE_MISSING` without it. A write from another mount or
+ * another browser tab of the same install refetches this one.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, useTapStorage } from '@tappify/extension-sdk';
+ *
+ * function CompactToggle() {
+ *   const preferences = useTapStorage('preferences');
+ *   return (
+ *     <TapButton
+ *       loading={preferences.isLoading}
+ *       onClick={() => void preferences.patch({ compact: true })}
+ *     >
+ *       Compact
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function useTapStorage<C extends TapSingletonName>(collection: C): TapStorageResult<TapSingletonDocument<C>>;
+
+/**
+ * Anything `cn` accepts: a class string, a number, an array of these, a map of
+ * class name to condition, or a value to drop.
+ */
+type ClassValue = ClassValue$1;
+/**
+ * Joins class names, dropping the ones that are `false`, `null` or `undefined`.
+ *
+ * @remarks
+ * This is `clsx`, re-exported so a vendor surface needs no class-name dependency
+ * of its own. It does not merge conflicting utility classes.
+ *
+ * @example
+ * ```tsx
+ * import { cn } from '@tappify/extension-sdk';
+ *
+ * function Row({ compact }: { compact: boolean }) {
+ *   return <div className={cn('starter-row', compact && 'starter-row--compact')} />;
+ * }
+ * ```
+ */
+declare function cn(...values: ClassValue[]): string;
+
+/** The props `TapButton` takes, on top of the native button attributes. */
+interface TapButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Defaults to `primary`. */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+    /** Defaults to `md`. */
+    size?: 'sm' | 'md';
+    /** Disables the button and marks it `aria-busy`. */
+    loading?: boolean;
+}
+/**
+ * Renders a button in the host's styling, in one of four variants.
+ *
+ * @remarks
+ * Draws on `--tap-accent` and `--tap-accent-fg` for `primary`, `--bg-raised`,
+ * `--fg-default` and `--divider` for `secondary`, `--fg-muted` for `ghost` and
+ * `--tap-danger` for `danger`, and takes its radius from `--tap-radius`. The
+ * element defaults to `type="button"`, so a button inside a `TapForm` does not
+ * submit it unless you pass `type="submit"`. `loading` disables the button, so a
+ * click cannot land twice.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton } from '@tappify/extension-sdk';
+ *
+ * function ExportRow({ busy, onExport }: { busy: boolean; onExport: () => void }) {
+ *   return (
+ *     <TapButton variant="secondary" size="sm" loading={busy} onClick={onExport}>
+ *       Export
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function TapButton({ variant, size, loading, disabled, className, children, ...rest }: TapButtonProps): ReactElement;
+/** The props `TapCard` takes. */
+interface TapCardProps {
+    /** Rendered in the header, which appears only with a `title` or an `action`. */
+    title?: ReactNode;
+    /** Sits at the end of the header, for a button or a link. */
+    action?: ReactNode;
+    /** Rendered under a divider below the body. */
+    footer?: ReactNode;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Renders the bordered surface a widget, tab or page section sits in.
+ *
+ * @remarks
+ * Renders as a `section` on `--bg-raised` with a `--divider` border and the
+ * `--tap-radius` corner, and the footer in `--fg-muted`. The header appears only
+ * when `title` or `action` is given, and the body carries its own padding, so
+ * nest content directly rather than wrapping it in another padded box. A widget
+ * belongs in one card.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapCard, TapStat } from '@tappify/extension-sdk';
+ *
+ * function InstallSummary() {
+ *   return (
+ *     <TapCard
+ *       title="Install summary"
+ *       action={<TapButton variant="ghost" size="sm">Compact</TapButton>}
+ *       footer={<span>Last seven days</span>}
+ *     >
+ *       <TapStat label="Installs" value="1,260" delta={0.087} />
+ *     </TapCard>
+ *   );
+ * }
+ * ```
+ */
+declare function TapCard({ title, action, footer, className, children, }: TapCardProps): ReactElement;
+/** The props `TapPageHeader` takes. */
+interface TapPageHeaderProps {
+    title: ReactNode;
+    description?: ReactNode;
+    /** Laid out in a row at the end of the header. */
+    actions?: ReactNode;
+}
+/**
+ * Renders the title, description and actions at the top of a tab, a page or a
+ * settings panel.
+ *
+ * @remarks
+ * The title renders as an `h2`, because the host owns the page's `h1`. The
+ * description follows `--fg-muted` and the rule under the header follows
+ * `--divider`. Under 360 pixels of mount width the actions stack under the title.
+ * A widget in a slot uses `TapCard`'s own header instead.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapPageHeader } from '@tappify/extension-sdk';
+ *
+ * function FunnelsHeader() {
+ *   return (
+ *     <TapPageHeader
+ *       title="Funnels"
+ *       description="Every step from impression to install."
+ *       actions={<TapButton size="sm">New funnel</TapButton>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapPageHeader({ title, description, actions, }: TapPageHeaderProps): ReactElement;
+/** The props `TapSkeleton` takes. */
+interface TapSkeletonProps {
+    /** How many bars to draw. Defaults to one. */
+    lines?: number;
+    /** A CSS width for every bar. Left out, each bar is 12% shorter than the last. */
+    width?: string;
+    className?: string;
+}
+/**
+ * Renders the placeholder bars that stand in for content while a read is in
+ * flight.
+ *
+ * @remarks
+ * The bars are `aria-hidden`, so a screen reader is not told about them, and they
+ * take their tone from `--bg-subtle`. The pulse stops under
+ * `prefers-reduced-motion`. Render this while `isLoading` is `true`, in place of
+ * the content rather than beside it.
+ *
+ * @example
+ * ```tsx
+ * import { TapSkeleton, TapStat, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Keywords() {
+ *   const keywords = useTapQuery({ kind: 'keywords' });
+ *   if (keywords.isLoading) return <TapSkeleton lines={3} />;
+ *   return <TapStat label="Tracked" value={keywords.data?.keywords.length ?? 0} />;
+ * }
+ * ```
+ */
+declare function TapSkeleton({ lines, width, className, }: TapSkeletonProps): ReactElement;
+/** The props `TapEmptyState` takes. */
+interface TapEmptyStateProps {
+    title: string;
+    description?: string;
+    /** Rendered under the text, for the one thing the owner can do next. */
+    action?: ReactNode;
+}
+/**
+ * Renders the centred message that stands in for content when there is nothing to
+ * show.
+ *
+ * @remarks
+ * Centres its text in `--fg-muted` with the title in `--fg-default`. Use it for an
+ * empty result or a surface the install has not been granted; a failure belongs in
+ * `TapErrorState`, which carries a retry and announces itself as an alert.
+ *
+ * @example
+ * ```tsx
+ * import { TapEmptyState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Reviews() {
+ *   const reviews = useTapQuery({
+ *     kind: 'reviews',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (reviews.data?.total === 0) {
+ *     return <TapEmptyState title="No reviews in this range" />;
+ *   }
+ *   return <span>{reviews.data?.total ?? 0} reviews</span>;
+ * }
+ * ```
+ */
+declare function TapEmptyState({ title, description, action, }: TapEmptyStateProps): ReactElement;
+/** The props `TapErrorState` takes. */
+interface TapErrorStateProps {
+    title: string;
+    /** The failure's own message, which is what a caller shows the owner. */
+    description?: string;
+    /** An error code, rendered small in `--font-mono` under the description. */
+    code?: string;
+    /** Renders a Retry button, and is called by it. */
+    onRetry?: () => void;
+}
+/**
+ * Renders the centred failure message a surface shows in place of its content.
+ *
+ * @remarks
+ * Carries `role="alert"`, so the host announces it, and draws the title in
+ * `--tap-danger`. The Retry button appears only with `onRetry`; wire it to the
+ * `refetch` of every read the surface needs. Pass the failure's own `message` as
+ * the description — an error from `useTapServer` carries the text your server sent
+ * the owner — and the `code` of a `TapError` or `TapServerError` as `code`.
+ *
+ * @example
+ * ```tsx
+ * import { TapErrorState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Crashes() {
+ *   const crashes = useTapQuery({
+ *     kind: 'crashes',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (crashes.error !== null) {
+ *     return (
+ *       <TapErrorState
+ *         title="Crashes did not load"
+ *         description={crashes.error.message}
+ *         onRetry={crashes.refetch}
+ *       />
+ *     );
+ *   }
+ *   return <span>{crashes.data?.issues.length ?? 0} issues</span>;
+ * }
+ * ```
+ */
+declare function TapErrorState({ title, description, code, onRetry, }: TapErrorStateProps): ReactElement;
+/** The props `TapStat` takes. */
+interface TapStatProps {
+    label: string;
+    value: ReactNode;
+    /** A share of the previous period, so `0.087` renders as `+9%`. */
+    delta?: number;
+    /** A line of context under the number. */
+    hint?: string;
+}
+/**
+ * Renders one labelled number, with an optional change against the previous
+ * period.
+ *
+ * @remarks
+ * The label is uppercased in `--fg-muted` and the number uses tabular figures, so
+ * a row of stats stays aligned as values change. `delta` is a ratio, not a
+ * percentage: it renders as whole percent with a plus in front when it is above
+ * zero, and is coloured `--tap-danger` below zero and `--tap-accent` at or above
+ * it. Format `value`
+ * yourself with `tap.format.number` or `tap.format.currency`, so it follows the
+ * owner's locale.
+ *
+ * @example
+ * ```tsx
+ * import { TapStat, useTap } from '@tappify/extension-sdk';
+ *
+ * function Installs({ installs, delta }: { installs: number; delta: number }) {
+ *   const tap = useTap();
+ *   return (
+ *     <TapStat
+ *       label="Installs"
+ *       value={tap.format.number(installs)}
+ *       delta={delta}
+ *       hint="Against the previous seven days"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapStat({ label, value, delta, hint, }: TapStatProps): ReactElement;
+/**
+ * The `TapInput` props for a single-line control, on top of the native input
+ * attributes minus `size`.
+ */
+interface TapSingleLineInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+}
+/**
+ * The `TapInput` props for a multiline control, on top of the native textarea
+ * attributes.
+ */
+interface TapTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+}
+/**
+ * The props `TapInput` takes: the single-line set, or the textarea set behind
+ * `multiline`.
+ */
+type TapInputProps = ({
+    multiline?: false;
+} & TapSingleLineInputProps) | ({
+    multiline: true;
+} & TapTextareaProps);
+/**
+ * Renders a labelled text control with its hint and error, as an input or, with
+ * `multiline`, a textarea.
+ *
+ * @remarks
+ * Generates an id when none is passed and binds the label, the hint and the error
+ * to the control, so the field is announced whole; an `error` also sets
+ * `aria-invalid` and the `--tap-danger` border. The textarea starts at four rows
+ * and is resizable in height. Pass `type="checkbox"` with
+ * `className="tap-control--checkbox"` for a boolean, which is what `TapForm`
+ * does.
+ *
+ * @example
+ * ```tsx
+ * import { TapInput } from '@tappify/extension-sdk';
+ *
+ * function TermField({ term, onTerm }: { term: string; onTerm: (next: string) => void }) {
+ *   return (
+ *     <TapInput
+ *       label="Keyword"
+ *       hint="One term per row in the report."
+ *       value={term}
+ *       onChange={event => onTerm(event.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapInput(props: TapInputProps): ReactElement;
+/** The props `TapSelect` takes, on top of the native select attributes. */
+interface TapSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+    /** Rendered in order; the component adds no empty option of its own. */
+    options: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * Renders a labelled select over a list of options, with its hint and error.
+ *
+ * @remarks
+ * Carries the same label, hint, error and `aria-describedby` wiring as
+ * `TapInput`. Add your own empty option when the field starts unset — `TapForm`
+ * puts a `Choose one` option in front of a schema's enum values.
+ *
+ * @example
+ * ```tsx
+ * import { TapSelect } from '@tappify/extension-sdk';
+ *
+ * function PlatformPicker({ value, onPick }: { value: string; onPick: (next: string) => void }) {
+ *   return (
+ *     <TapSelect
+ *       label="Platform"
+ *       value={value}
+ *       options={[
+ *         { value: 'ios', label: 'iOS' },
+ *         { value: 'android', label: 'Android' },
+ *       ]}
+ *       onChange={event => onPick(event.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapSelect({ label, error, hint, options, className, id, ...rest }: TapSelectProps): ReactElement;
+/** One column of a `TapTable`. */
+interface TapTableColumnDef<T> {
+    /** The key read from each row when there is no `render`. */
+    key: string;
+    label: string;
+    /** `end` right-aligns the column and gives it tabular figures. */
+    align?: 'start' | 'end';
+    /** Draws the cell. Without it the cell shows the row's own string or number. */
+    render?(row: T): ReactNode;
+}
+/** The props `TapTable` takes. */
+interface TapTableProps<T> {
+    columns: TapTableColumnDef<T>[];
+    rows: T[];
+    /** Returns a stable key per row, which React uses for reconciliation. */
+    rowKey: (row: T) => string;
+    /** Rendered in place of the whole table when `rows` is empty. */
+    empty?: ReactNode;
+    /** Makes each row clickable and focusable, and is called on click or Enter. */
+    onRowClick?: (row: T) => void;
+}
+/**
+ * Renders rows under column headers, scrolling sideways inside the mount rather
+ * than widening it.
+ *
+ * @remarks
+ * A cell with no `render` shows the row's own value under `key` when that value is
+ * a string, number, boolean or bigint, and nothing otherwise, so an object or an
+ * array needs a `render`. With `empty` and no rows, the table is replaced whole by
+ * that node. With `onRowClick` each row becomes focusable and answers Enter and
+ * Space as well as a click, and hovers on `--bg-subtle`; the headers and rules
+ * follow `--fg-muted` and `--divider`.
+ *
+ * @example
+ * ```tsx
+ * import { TapEmptyState, TapTable, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Keywords() {
+ *   const keywords = useTapQuery({ kind: 'keywords' });
+ *   return (
+ *     <TapTable
+ *       columns={[
+ *         { key: 'term', label: 'Term' },
+ *         { key: 'position', label: 'Rank', align: 'end' },
+ *       ]}
+ *       rows={keywords.data?.keywords ?? []}
+ *       rowKey={keyword => keyword.id}
+ *       empty={<TapEmptyState title="No keywords tracked yet" />}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapTable<T>({ columns, rows, rowKey, empty, onRowClick, }: TapTableProps<T>): ReactElement;
+
+/** The props `TapDialog` takes. */
+interface TapDialogProps {
+    /** The dialog renders nothing while this is `false`. */
+    open: boolean;
+    /** Rendered in the header, and used as the dialog's accessible name. */
+    title: string;
+    /** Called by Escape, by a click on the scrim, and by the host's close event. */
+    onClose: () => void;
+    /** Rendered under a divider at the end, for the dialog's buttons. */
+    footer?: ReactNode;
+    children: ReactNode;
+    /** The id of your own heading, when the accessible name is not the title. */
+    labelledBy?: string;
+}
+/**
+ * Renders a modal dialog into the mount's own portal node, so it covers the
+ * surface without leaving the extension.
+ *
+ * @remarks
+ * Rendered outside a Tappify mount it throws `TAP_OUTSIDE_HOST`, from the `useTap`
+ * above it. Inside a mount whose shadow root has no portal node yet, opening it
+ * throws `TapError` with code `TAP_NO_PORTAL`; `renderWithTap` provides that node
+ * in tests. While open it traps Tab
+ * inside itself, moves focus to the first focusable element and returns focus
+ * where it was on close, and answers Escape and a click on the scrim with
+ * `onClose`. The scrim follows `--tap-scrim` and the panel `--bg-raised`,
+ * `--divider` and `--tap-radius`; the panel is at most 520 pixels wide. The
+ * component keeps no open state of its own.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapDialog } from '@tappify/extension-sdk';
+ * import { useState } from 'react';
+ *
+ * function ExportDialog() {
+ *   const [open, setOpen] = useState(false);
+ *   return (
+ *     <>
+ *       <TapButton onClick={() => setOpen(true)}>Export</TapButton>
+ *       <TapDialog
+ *         open={open}
+ *         title="Export keywords"
+ *         onClose={() => setOpen(false)}
+ *         footer={<TapButton onClick={() => setOpen(false)}>Done</TapButton>}
+ *       >
+ *         <span>The report covers the range in the filter bar.</span>
+ *       </TapDialog>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function TapDialog({ open, title, onClose, footer, children, labelledBy, }: TapDialogProps): ReactElement | null;
+
+/** The control a schema property maps to. */
+type TapFormFieldKind = 'text' | 'textarea' | 'date' | 'number' | 'boolean' | 'enum';
+/** One control `TapForm` renders, as `formFields` reads it off a schema. */
+interface TapFormField {
+    /** The property name in the schema, and the key in the submitted value. */
+    name: string;
+    /** The property's `title`, or the name spaced and capitalised. */
+    label: string;
+    kind: TapFormFieldKind;
+    /** Whether the schema lists the property under `required`. */
+    required: boolean;
+    /** The property's `description`. */
+    hint?: string;
+    /** Set for an `enum` property: one option per string value. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * Reads a JSON Schema object and returns the list of controls `TapForm` renders
+ * from it.
+ *
+ * @remarks
+ * One field per declared property, in the order the schema lists them; a schema
+ * with no `properties` object returns an empty list, and a property that is not an
+ * object is skipped. An `enum` becomes a select and keeps only its string values;
+ * otherwise the kind comes from `type` — `boolean`, `number` and `integer` — and
+ * then from `format`, where `textarea` and `date` are recognised and anything else
+ * falls back to a single-line text control. Nested objects and arrays get a text
+ * control, so render those yourself. Call it when you want the fields without the
+ * form.
+ *
+ * @example
+ * ```ts
+ * import { formFields } from '@tappify/extension-sdk';
+ *
+ * const fields = formFields({
+ *   type: 'object',
+ *   properties: { refreshMinutes: { type: 'integer', title: 'Refresh minutes' } },
+ *   required: ['refreshMinutes'],
+ * });
+ * const names = fields.map(field => field.name);
+ * ```
+ */
+declare function formFields(schema: JsonSchema): TapFormField[];
+/** The props `TapForm` takes. */
+interface TapFormProps<T> {
+    /** The object schema to render, one control per declared property. */
+    schema: JsonSchema;
+    /** The value the fields start at; later changes to it do not reset the form. */
+    value?: Partial<T>;
+    /** Defaults to `Submit`. */
+    submitLabel?: string;
+    /** Defaults to `Cancel`. */
+    cancelLabel?: string;
+    /** Marks the submit button busy and disables it while a submit is in flight. */
+    busy?: boolean;
+    /** Called with the cleaned value once validation passes. */
+    onSubmit: (value: T) => void | Promise<void>;
+    /** Renders a cancel button next to submit, and is called by it. */
+    onCancel?: () => void;
+}
+/**
+ * Renders a JSON Schema as a form in the host's styling, validates it on submit
+ * and hands back the value.
+ *
+ * @remarks
+ * Point it at the same schema file the manifest references, so the form and the
+ * handler change together. Submit drops the fields left blank, then checks what
+ * remains against the whole schema, so a `minimum`, `pattern` or `maxLength`
+ * lands under the control it belongs to; a required field left empty is reported
+ * without reaching the schema. A schema this SDK's Zod version cannot compile
+ * still renders and still enforces required fields. `onSubmit` runs only when
+ * nothing failed, and the form holds its own values, so a change to `value` after
+ * the first render does not reset it. A form with no `value` has nothing to infer
+ * `T` from, so annotate the handler's parameter.
+ *
+ * @example
+ * ```tsx
+ * import { TapForm, type TapSettingsProps } from '@tappify/extension-sdk';
+ *
+ * const schema = {
+ *   type: 'object',
+ *   properties: { refreshMinutes: { type: 'integer', title: 'Refresh minutes' } },
+ *   required: ['refreshMinutes'],
+ * };
+ *
+ * function Settings({ values, onChange }: TapSettingsProps) {
+ *   return (
+ *     <TapForm
+ *       schema={schema}
+ *       value={values}
+ *       submitLabel="Save"
+ *       onSubmit={next => onChange(next)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapForm<T>({ schema, value, submitLabel, cancelLabel, busy, onSubmit, onCancel, }: TapFormProps<T>): ReactElement;
+
+export { type ClassValue, Tap, TapButton, type TapButtonProps, TapCard, type TapCardProps, TapDialog, type TapDialogProps, TapEmptyState, type TapEmptyStateProps, TapErrorState, type TapErrorStateProps, TapFilters, TapForm, type TapFormField, type TapFormFieldKind, type TapFormProps, TapHostEvents, TapInput, type TapInputProps, TapPageHeader, type TapPageHeaderProps, TapProcedureInput, TapProcedureName, TapProcedureOutput, TapQuery, type TapQueryOptions, type TapQueryResult, TapResult, TapSelect, type TapSelectProps, type TapSingleLineInputProps, TapSingletonDocument, TapSingletonName, TapSize, TapSkeleton, type TapSkeletonProps, TapStat, type TapStatProps, type TapStorageResult, TapTable, type TapTableColumnDef, type TapTableProps, type TapTextareaProps, cn, dataQueryKey, formFields, installPrefix, procedurePrefix, procedureQueryKey, storageQueryKey, useTapAuth, useTapContext, useTapFilters, useTapParams, useTapProject, useTapQuery, useTapServer, useTapSize, useTapState, useTapStorage, useTapTheme };