@tappify/extension-sdk 2.0.0

package/dist/constants-DJ_KgZpN.d.ts

@@ -0,0 +1,449 @@
+type JsonSchema = Record<string, unknown>;
+type ExtensionVisibility = 'public' | 'unlisted' | 'private';
+type ExtensionInstallScope = 'project' | 'organization';
+interface ScopeEntry {
+    key: ScopeKey;
+    justification?: string;
+}
+interface ProcedureDeclaration {
+    input: JsonSchema;
+    output: JsonSchema;
+    cache?: '1m' | '5m' | '1h';
+    kind?: 'read' | 'write';
+}
+interface StorageCollection {
+    scope: 'user' | 'install' | 'organization';
+    singleton?: boolean;
+    schema: JsonSchema;
+}
+interface PageContribution {
+    id: string;
+    title: string;
+    entry: string;
+    nav?: boolean;
+    mobile?: boolean;
+}
+interface TabContribution {
+    id: string;
+    title: string;
+    entry: string;
+    page: HostPage;
+    mobile?: boolean;
+}
+interface WidgetContribution {
+    id: string;
+    title: string;
+    entry: string;
+    page: HostPage;
+    slot: SlotId;
+    size: '1x1' | '2x1' | '2x2';
+    expandable?: boolean;
+}
+interface SeriesContribution {
+    id: string;
+    label: string;
+    chart: HostChart;
+    metric: string;
+}
+interface BannerContribution {
+    id: string;
+    page: HostPage;
+    event: string;
+}
+interface RowActionContribution {
+    id: string;
+    title: string;
+    table: HostTable;
+    entry: string;
+}
+interface MarkerContribution {
+    id: string;
+    label: string;
+    chart: HostChart | '*';
+    event: string;
+    glyph: string;
+}
+interface SettingsContribution {
+    entry: string;
+    schema: JsonSchema;
+}
+interface CredentialField {
+    name: string;
+    label: string;
+    type: 'text' | 'password' | 'textarea' | 'file' | 'select';
+    required: boolean;
+    options?: string[];
+    help?: string;
+}
+interface ConnectorAuth {
+    method: 'none' | 'api_key' | 'oauth';
+    fields?: CredentialField[];
+    oauth?: {
+        authorizationUrl: string;
+        tokenUrl: string;
+        scopes: string[];
+    };
+}
+interface DimensionDeclaration {
+    key: string;
+    label: string;
+}
+interface MetricDeclaration {
+    key: string;
+    label: string;
+    unit: 'count' | 'ratio' | 'currency' | 'seconds' | 'bytes';
+    kind: 'gauge' | 'counter';
+    dimensions?: DimensionDeclaration[];
+    backfillDays?: number;
+}
+interface ConnectorContribution {
+    auth?: ConnectorAuth;
+    sync?: '5m' | '15m' | '1h' | '6h' | '24h';
+    metrics?: MetricDeclaration[];
+}
+interface WebhookContribution {
+    event: string;
+    as: 'alert' | 'banner' | 'event';
+    payload: JsonSchema;
+}
+interface ToolDeclaration {
+    id: string;
+    description: string;
+    input: JsonSchema;
+    returns: 'comparison' | 'table' | 'series' | 'list' | 'value';
+    cost: 'low' | 'medium' | 'high';
+    cache?: '1m' | '5m' | '1h';
+}
+interface MentionDeclaration {
+    id: string;
+    label: string;
+    list: string;
+}
+interface ActionDeclaration {
+    id: string;
+    description: string;
+    input: JsonSchema;
+    approval: true;
+    reversible: boolean;
+    scope: ScopeKey;
+    estimatesCost?: boolean;
+}
+interface KnowledgeDeclaration {
+    id: string;
+    category: 'metric_definitions' | 'gotchas' | 'setup';
+    file: string;
+}
+interface SkillDeclaration {
+    id: string;
+    name: string;
+    description: string;
+    file: string;
+    tools?: string[];
+}
+interface PromptDeclaration {
+    id: string;
+    title: string;
+    template: string;
+    surfaces: ('chat_suggestion' | 'widget' | 'page' | 'result_card')[];
+    after?: string[];
+    input?: JsonSchema;
+}
+interface ContextDeclaration {
+    id: string;
+    description: string;
+    when: ('turn_start' | 'mention')[];
+    cache?: '1m' | '5m' | '1h';
+}
+interface AiContribution {
+    tools?: ToolDeclaration[];
+    mentions?: MentionDeclaration[];
+    actions?: ActionDeclaration[];
+    knowledge?: KnowledgeDeclaration[];
+    skills?: SkillDeclaration[];
+    prompts?: PromptDeclaration[];
+    context?: ContextDeclaration[];
+}
+interface WorkContribution {
+    kind: 'tracker' | 'docs' | 'chat';
+    container: {
+        label: string;
+        list: string;
+    };
+    creates: ('issue' | 'page' | 'message')[];
+    fields: {
+        priority?: string[];
+        labels?: boolean;
+        assignee?: boolean;
+        required: string[];
+    };
+    attachments: ('image' | 'link')[];
+    comments: 'two-way' | 'none';
+    status?: {
+        webhook: string;
+        map: Record<'open' | 'in_progress' | 'done', string[]>;
+    };
+    identity: 'user' | 'install';
+}
+interface ExtensionListing {
+    longDescription?: string;
+    screenshots?: string[];
+    website?: string;
+    supportUrl?: string;
+    privacyUrl?: string;
+}
+interface ExtensionManifest {
+    $schema?: string;
+    id: string;
+    name: string;
+    description: string;
+    icon: string;
+    category: ExtensionCategory;
+    sdk: string;
+    visibility: ExtensionVisibility;
+    installScope: ExtensionInstallScope;
+    scopes: ScopeEntry[];
+    contributes: {
+        pages?: PageContribution[];
+        tabs?: TabContribution[];
+        widgets?: WidgetContribution[];
+        series?: SeriesContribution[];
+        banners?: BannerContribution[];
+        rowActions?: RowActionContribution[];
+        markers?: MarkerContribution[];
+        settings?: SettingsContribution;
+        storage?: Record<string, StorageCollection>;
+        connector?: ConnectorContribution;
+        webhooks?: WebhookContribution[];
+        ai?: AiContribution;
+        work?: WorkContribution;
+    };
+    server?: {
+        baseUrl: string;
+        sandboxBaseUrl?: string;
+        procedures?: Record<string, ProcedureDeclaration>;
+        events?: HostEventName[];
+    };
+    telemetry?: string[];
+    listing?: ExtensionListing;
+    pricing?: never;
+    score?: never;
+}
+type ExposableKind = 'page' | 'tab' | 'widget' | 'rowAction' | 'settings';
+interface UiContributionRef {
+    kind: ExposableKind;
+    id: string;
+    entry: string;
+    expose: string;
+}
+interface ManifestIssue {
+    path: string;
+    message: string;
+}
+type ManifestValidation = {
+    ok: true;
+    manifest: ExtensionManifest;
+} | {
+    ok: false;
+    issues: ManifestIssue[];
+};
+
+declare const SCOPES: readonly [{
+    readonly key: "ui:render";
+    readonly label: "Render UI";
+    readonly description: "Render the declared pages, tabs, widgets, row actions and settings panel, and open chat with a visible prompt";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "projects:read";
+    readonly label: "Read the project";
+    readonly description: "Project name, platforms and store identity";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "analytics:read";
+    readonly label: "Read analytics";
+    readonly description: "Downloads, impressions, page views and conversion series";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "store.metadata:read";
+    readonly label: "Read store metadata";
+    readonly description: "Listing metadata, keyword set and keyword positions";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "reviews:read";
+    readonly label: "Read store reviews";
+    readonly description: "Review text, ratings and replies";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "crashes:read";
+    readonly label: "Read crash data";
+    readonly description: "Crash-free rate and issue counts";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "revenue:read";
+    readonly label: "Read revenue";
+    readonly description: "MRR, revenue series and refund counts";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "metrics:write";
+    readonly label: "Write connector metrics";
+    readonly description: "Write the metrics this extension declares into the metrics store";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "alerts:write";
+    readonly label: "Raise alerts and banners";
+    readonly description: "Turn declared webhooks into alerts and banners, at most three a day per project";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "insights:write";
+    readonly label: "Post insights";
+    readonly description: "Post insights to Home and to chat";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "ai:tools";
+    readonly label: "Add assistant tools";
+    readonly description: "Offer tools and mentions to the assistant";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "ai:actions";
+    readonly label: "Run assistant actions";
+    readonly description: "Run declared actions, each behind the approval card";
+    readonly requiresSecurityReview: true;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "store.metadata:write";
+    readonly label: "Propose store metadata changes";
+    readonly description: "Propose listing changes through a Tappify approval";
+    readonly requiresSecurityReview: true;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "autopilot:trigger";
+    readonly label: "Trigger automated store actions";
+    readonly description: "Start automated store actions on the owner’s behalf";
+    readonly requiresSecurityReview: true;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "work:create";
+    readonly label: "Create work items";
+    readonly description: "Create issues, pages or messages in the vendor’s system";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "work:sync";
+    readonly label: "Sync work items";
+    readonly description: "Two-way comments and status on created work items";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "storage:write";
+    readonly label: "Use hosted storage";
+    readonly description: "Read and write this extension’s own hosted storage collections";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: false;
+}, {
+    readonly key: "messaging:send";
+    readonly label: "Send messages to end users";
+    readonly description: "Send messages or push notifications to the owner’s end users through owner-supplied credentials";
+    readonly requiresSecurityReview: true;
+    readonly requiresJustification: true;
+}, {
+    readonly key: "ai:skills";
+    readonly label: "Shape the assistant";
+    readonly description: "Add skills, prompt templates and context providers that shape the assistant’s behaviour";
+    readonly requiresSecurityReview: false;
+    readonly requiresJustification: true;
+}];
+type ScopeDefinition = (typeof SCOPES)[number];
+/** Every scope an extension can ask for under `scopes` in its manifest. */
+type ScopeKey = ScopeDefinition['key'];
+declare const SCOPE_KEYS: readonly ScopeKey[];
+declare const SLOTS: readonly ["kpi-row", "insights", "sidebar", "below-chart", "below-list"];
+/** The anchors on a host page a widget can be declared at. */
+type SlotId = (typeof SLOTS)[number];
+declare const CHARTS: readonly ["installs-activity", "conversion", "release-cadence"];
+type HostChart = (typeof CHARTS)[number];
+declare const PAGES: readonly [{
+    readonly key: "overview";
+    readonly label: "Home";
+    readonly route: "/projects/:id/overview";
+    readonly slots: readonly ["kpi-row", "insights", "sidebar"];
+    readonly charts: readonly ["installs-activity"];
+    readonly tabs: true;
+    readonly banners: true;
+}, {
+    readonly key: "analytics";
+    readonly label: "Analytics";
+    readonly route: "/projects/:id/analytics";
+    readonly slots: readonly ["kpi-row", "below-chart", "sidebar"];
+    readonly charts: readonly ["installs-activity", "conversion"];
+    readonly tabs: true;
+    readonly banners: true;
+}, {
+    readonly key: "deployments";
+    readonly label: "Deployments";
+    readonly route: "/projects/:id/deployments";
+    readonly slots: readonly ["sidebar", "below-list"];
+    readonly charts: readonly ["release-cadence"];
+    readonly tabs: true;
+    readonly banners: false;
+}, {
+    readonly key: "ai_chat";
+    readonly label: "Assistant";
+    readonly route: "chat";
+    readonly slots: readonly [];
+    readonly charts: readonly [];
+    readonly tabs: false;
+    readonly banners: false;
+}];
+type PageDefinition = (typeof PAGES)[number];
+/** The host pages a contribution can attach a tab, widget or banner to. */
+type HostPage = PageDefinition['key'];
+declare const PAGE_KEYS: readonly HostPage[];
+declare const TABLES: readonly [{
+    readonly key: "analytics.keywords";
+    readonly label: "Keywords";
+}, {
+    readonly key: "analytics.reviews";
+    readonly label: "Reviews";
+}, {
+    readonly key: "deployments.releases";
+    readonly label: "Releases";
+}, {
+    readonly key: "deployments.builds";
+    readonly label: "Builds";
+}];
+type TableDefinition = (typeof TABLES)[number];
+type HostTable = TableDefinition['key'];
+declare const TABLE_KEYS: readonly HostTable[];
+declare const KINDS: readonly ["page", "tab", "widget", "series", "banner", "rowAction", "marker", "settings", "storage", "connector", "webhook", "tool", "mention", "action", "knowledge", "skill", "prompt", "context", "work"];
+type ContributionKind = (typeof KINDS)[number];
+declare const CATEGORIES: readonly ["market_data", "subscriptions", "product_analytics", "crashes", "attribution", "experiments", "messaging", "session_replay", "localization", "design", "ci_cd", "trackers", "support", "chat", "ad_monetization", "warehouse", "compliance", "additional_stores"];
+type ExtensionCategory = (typeof CATEGORIES)[number];
+declare const EVENTS: readonly ["release.shipped", "metadata.changed", "keyword.set_changed", "screenshots.updated", "price.changed", "featuring.started", "score.changed", "incident.opened", "incident.resolved", "playbook.step_approved", "review.thread_opened", "review.thread_resolved", "approval.requested", "digest.sent", "install.created", "install.paused", "install.resumed", "install.revoked", "install.token_rotated", "scopes.changed", "settings.changed"];
+/** Every event Tappify emits, which a mount or a server can subscribe to. */
+type HostEventName = (typeof EVENTS)[number];
+declare const SERVED_SDK_MAJORS: readonly number[];
+/** The `kind` of every read `tap.data.query` accepts, one per scope it needs. */
+type DataQueryKind = 'project' | 'series' | 'keywords' | 'listing' | 'reviews' | 'crashes' | 'revenue';
+declare const QUERY_SCOPES: Record<DataQueryKind, ScopeKey>;
+/**
+ * The keys a tool's answer carries for each `returns` kind it may declare.
+ * `validateToolResponse`, `tappify extension doctor` and the host all read
+ * this one table, so a wrong body fails the same way wherever it is checked.
+ */
+declare const CARD_KEYS: Record<ToolDeclaration['returns'], string[]>;
+declare const findScope: (key: string) => ScopeDefinition | undefined;
+declare const findPage: (key: string) => PageDefinition | undefined;
+declare const findTable: (key: string) => TableDefinition | undefined;
+declare const slotsForPage: (page: string) => readonly SlotId[];
+
+export { TABLES as $, type ActionDeclaration as A, type BannerContribution as B, CARD_KEYS as C, type DataQueryKind as D, type ExtensionManifest as E, type PageDefinition as F, type ProcedureDeclaration as G, type HostEventName as H, type PromptDeclaration as I, type JsonSchema as J, KINDS as K, SCOPES as L, type ManifestValidation as M, SCOPE_KEYS as N, SERVED_SDK_MAJORS as O, PAGES as P, QUERY_SCOPES as Q, type RowActionContribution as R, type ScopeKey as S, SLOTS as T, type UiContributionRef as U, type ScopeDefinition as V, type ScopeEntry as W, type SeriesContribution as X, type SettingsContribution as Y, type SkillDeclaration as Z, type StorageCollection as _, type HostPage as a, TABLE_KEYS as a0, type TabContribution as a1, type TableDefinition as a2, type ToolDeclaration as a3, type WebhookContribution as a4, type WidgetContribution as a5, type WorkContribution as a6, findPage as a7, findScope as a8, findTable as a9, slotsForPage as aa, type SlotId as b, type ExposableKind as c, type AiContribution as d, CATEGORIES as e, CHARTS as f, type ConnectorAuth as g, type ConnectorContribution as h, type ContextDeclaration as i, type ContributionKind as j, type CredentialField as k, type DimensionDeclaration as l, EVENTS as m, type ExtensionCategory as n, type ExtensionInstallScope as o, type ExtensionListing as p, type ExtensionVisibility as q, type HostChart as r, type HostTable as s, type KnowledgeDeclaration as t, type ManifestIssue as u, type MarkerContribution as v, type MentionDeclaration as w, type MetricDeclaration as x, PAGE_KEYS as y, type PageContribution as z };

package/dist/context-Dt6xh_5t.d.cts

@@ -0,0 +1,30 @@
+import { Context } from 'react';
+import { T as Tap } from './types-DrpQSv_2.cjs';
+
+declare const TapContext: Context<Tap | null>;
+/**
+ * Returns the whole bridge the host mounted this component with.
+ *
+ * @remarks
+ * Throws `TapError` with code `TAP_OUTSIDE_HOST` when no Tappify mount is above
+ * the component. The object it returns does not re-render the component when the
+ * host changes a member; read through `useTapFilters`, `useTapTheme` and the
+ * other slice hooks where that matters.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, useTap } from '@tappify/extension-sdk';
+ *
+ * function CopyId() {
+ *   const tap = useTap();
+ *   return (
+ *     <TapButton onClick={() => void tap.ui.copy(tap.project.id)}>
+ *       Copy project id
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function useTap(): Tap;
+
+export { TapContext as T, useTap as u };

package/dist/context-Ml7k_V14.d.ts

@@ -0,0 +1,30 @@
+import { Context } from 'react';
+import { T as Tap } from './types-DDAGLpov.js';
+
+declare const TapContext: Context<Tap | null>;
+/**
+ * Returns the whole bridge the host mounted this component with.
+ *
+ * @remarks
+ * Throws `TapError` with code `TAP_OUTSIDE_HOST` when no Tappify mount is above
+ * the component. The object it returns does not re-render the component when the
+ * host changes a member; read through `useTapFilters`, `useTapTheme` and the
+ * other slice hooks where that matters.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, useTap } from '@tappify/extension-sdk';
+ *
+ * function CopyId() {
+ *   const tap = useTap();
+ *   return (
+ *     <TapButton onClick={() => void tap.ui.copy(tap.project.id)}>
+ *       Copy project id
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function useTap(): Tap;
+
+export { TapContext as T, useTap as u };

package/dist/errors-COsBh7kd.d.cts

@@ -0,0 +1,88 @@
+/** Every code a `TapError` the SDK raises carries. */
+type TapErrorCode = 'TAP_OUTSIDE_HOST' | 'TAP_SCOPE_MISSING' | 'TAP_UNKNOWN_COLLECTION' | 'TAP_UNKNOWN_PROCEDURE' | 'TAP_NO_PORTAL' | 'TAP_NO_QUERY_CLIENT' | 'TAP_MANIFEST_INVALID' | 'TAP_ENTRY_MISSING' | 'TAP_STYLES_UNRESOLVED' | 'TAP_SCHEMA_UNRESOLVED' | 'TAP_TOKEN_MISSING' | 'TAP_TOKEN_INVALID' | 'TAP_TOKEN_AUDIENCE' | 'TAP_EVENT_ID_MISSING' | 'TAP_BODY_INVALID' | 'TAP_BODY_TOO_LARGE' | 'TAP_ROUTE_UNKNOWN' | 'TAP_HANDLER_MISSING' | 'TAP_INTERNAL_ERROR' | 'TAP_WEBHOOK_REJECTED' | 'TAP_TEST_TARGET_INVALID';
+/**
+ * The same codes as `TapErrorCode`, as an array to iterate or check membership
+ * against at runtime.
+ */
+declare const TAP_ERROR_CODES: readonly TapErrorCode[];
+/**
+ * The error the SDK and the host raise when a call cannot be served at all.
+ *
+ * @remarks
+ * The SDK throws it for a mount outside the host (`TAP_OUTSIDE_HOST`), a
+ * collection or procedure the manifest does not declare
+ * (`TAP_UNKNOWN_COLLECTION`, `TAP_UNKNOWN_PROCEDURE`), a missing portal or query
+ * client, a token the server rejected, and a misused testing helper. The host
+ * turns a refused read or write into `TAP_SCOPE_MISSING`. Branch on `code`, which
+ * is stable; the message is prose and changes. An error your own server raised is
+ * a `TapServerError` instead.
+ *
+ * @example
+ * ```tsx
+ * import { TapError, TapErrorState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Revenue() {
+ *   const revenue = useTapQuery({
+ *     kind: 'revenue',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (TapError.is(revenue.error) && revenue.error.code === 'TAP_SCOPE_MISSING') {
+ *     return <TapErrorState title="Revenue is not shared with this extension" />;
+ *   }
+ *   return <span>{revenue.data?.mrr ?? 0}</span>;
+ * }
+ * ```
+ */
+declare class TapError extends Error {
+    readonly code: TapErrorCode;
+    constructor(code: TapErrorCode, message: string);
+    /**
+     * Narrows an unknown value to a `TapError`, by name and by a code it
+     * recognises, so it holds across module instances.
+     */
+    static is(value: unknown): value is TapError;
+}
+/**
+ * The error a vendor server throws to answer a Tappify call with a code and a
+ * message the owner sees.
+ *
+ * @remarks
+ * `createTappifyHandler` catches it and answers `{ error: { code, message } }`
+ * with `status`, or 400 when no status was given; the host relays both to the
+ * calling mount, where they arrive as the `error` of `useTapServer`. Pick a code
+ * of your own and keep it stable — the SDK's own codes are `SERVER_ERROR_CODES` —
+ * and write the message for the owner, who reads it on screen.
+ *
+ * @example
+ * ```ts
+ * import { TapServerError } from '@tappify/extension-sdk/server';
+ *
+ * function assertRange(days: number) {
+ *   if (days > 0) return;
+ *   throw new TapServerError(
+ *     'RANGE_TOO_SHORT',
+ *     'getSummary needs a range of at least one day. Widen the date picker, then retry.',
+ *     400,
+ *   );
+ * }
+ * ```
+ */
+declare class TapServerError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(code: string, message: string, status?: number);
+    /** The wire body the handler answers with, without the status. */
+    toJSON(): {
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+    /**
+     * Narrows an unknown value to a `TapServerError` by name and by carrying a
+     * string `code`, so it holds across module instances.
+     */
+    static is(value: unknown): value is TapServerError;
+}
+
+export { TAP_ERROR_CODES as T, TapError as a, type TapErrorCode as b, TapServerError as c };

package/dist/errors-COsBh7kd.d.ts

@@ -0,0 +1,88 @@
+/** Every code a `TapError` the SDK raises carries. */
+type TapErrorCode = 'TAP_OUTSIDE_HOST' | 'TAP_SCOPE_MISSING' | 'TAP_UNKNOWN_COLLECTION' | 'TAP_UNKNOWN_PROCEDURE' | 'TAP_NO_PORTAL' | 'TAP_NO_QUERY_CLIENT' | 'TAP_MANIFEST_INVALID' | 'TAP_ENTRY_MISSING' | 'TAP_STYLES_UNRESOLVED' | 'TAP_SCHEMA_UNRESOLVED' | 'TAP_TOKEN_MISSING' | 'TAP_TOKEN_INVALID' | 'TAP_TOKEN_AUDIENCE' | 'TAP_EVENT_ID_MISSING' | 'TAP_BODY_INVALID' | 'TAP_BODY_TOO_LARGE' | 'TAP_ROUTE_UNKNOWN' | 'TAP_HANDLER_MISSING' | 'TAP_INTERNAL_ERROR' | 'TAP_WEBHOOK_REJECTED' | 'TAP_TEST_TARGET_INVALID';
+/**
+ * The same codes as `TapErrorCode`, as an array to iterate or check membership
+ * against at runtime.
+ */
+declare const TAP_ERROR_CODES: readonly TapErrorCode[];
+/**
+ * The error the SDK and the host raise when a call cannot be served at all.
+ *
+ * @remarks
+ * The SDK throws it for a mount outside the host (`TAP_OUTSIDE_HOST`), a
+ * collection or procedure the manifest does not declare
+ * (`TAP_UNKNOWN_COLLECTION`, `TAP_UNKNOWN_PROCEDURE`), a missing portal or query
+ * client, a token the server rejected, and a misused testing helper. The host
+ * turns a refused read or write into `TAP_SCOPE_MISSING`. Branch on `code`, which
+ * is stable; the message is prose and changes. An error your own server raised is
+ * a `TapServerError` instead.
+ *
+ * @example
+ * ```tsx
+ * import { TapError, TapErrorState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Revenue() {
+ *   const revenue = useTapQuery({
+ *     kind: 'revenue',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (TapError.is(revenue.error) && revenue.error.code === 'TAP_SCOPE_MISSING') {
+ *     return <TapErrorState title="Revenue is not shared with this extension" />;
+ *   }
+ *   return <span>{revenue.data?.mrr ?? 0}</span>;
+ * }
+ * ```
+ */
+declare class TapError extends Error {
+    readonly code: TapErrorCode;
+    constructor(code: TapErrorCode, message: string);
+    /**
+     * Narrows an unknown value to a `TapError`, by name and by a code it
+     * recognises, so it holds across module instances.
+     */
+    static is(value: unknown): value is TapError;
+}
+/**
+ * The error a vendor server throws to answer a Tappify call with a code and a
+ * message the owner sees.
+ *
+ * @remarks
+ * `createTappifyHandler` catches it and answers `{ error: { code, message } }`
+ * with `status`, or 400 when no status was given; the host relays both to the
+ * calling mount, where they arrive as the `error` of `useTapServer`. Pick a code
+ * of your own and keep it stable — the SDK's own codes are `SERVER_ERROR_CODES` —
+ * and write the message for the owner, who reads it on screen.
+ *
+ * @example
+ * ```ts
+ * import { TapServerError } from '@tappify/extension-sdk/server';
+ *
+ * function assertRange(days: number) {
+ *   if (days > 0) return;
+ *   throw new TapServerError(
+ *     'RANGE_TOO_SHORT',
+ *     'getSummary needs a range of at least one day. Widen the date picker, then retry.',
+ *     400,
+ *   );
+ * }
+ * ```
+ */
+declare class TapServerError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(code: string, message: string, status?: number);
+    /** The wire body the handler answers with, without the status. */
+    toJSON(): {
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+    /**
+     * Narrows an unknown value to a `TapServerError` by name and by carrying a
+     * string `code`, so it holds across module instances.
+     */
+    static is(value: unknown): value is TapServerError;
+}
+
+export { TAP_ERROR_CODES as T, TapError as a, type TapErrorCode as b, TapServerError as c };