@tappify/extension-sdk 2.0.0

package/dist/testing/index.d.ts

@@ -0,0 +1,512 @@
+import { JSONWebKeySet } from 'jose';
+import { a as TapFilters, N as TapProjectResult, o as TapApp, Q as TapRelease, D as TapKeyword, F as TapListing, U as TapReviewsResult, v as TapCrashesResult, R as TapRevenueResult, W as TapSeriesMetric, Y as TapSeriesResult, d as TapQuery, e as TapResult, b as TapSize, T as Tap, a6 as TapToastTone, t as TapConfirmOptions, q as TapChatCard, c as TapHostEvents } from '../types-DDAGLpov.js';
+import { h as TappifyHealth, b as MetricsInput, c as MetricsResponse, M as MentionItems, C as ContextBlock, W as WorkOperation, i as TappifyInstall, g as TappifyHandlerOptions, a as TappifyClaims, T as TappifyFetchHandler } from '../handler-CZIlZ5vu.js';
+export { M as MatcherResult, a as MatcherTarget, r as registerTapMatchers, t as tapMatchers } from '../matchers-Cz93AK1n.js';
+import { S as ScopeKey, x as MetricDeclaration, a3 as ToolDeclaration } from '../constants-DJ_KgZpN.js';
+import { QueryClient } from '@tanstack/react-query';
+import { RenderOptions, RenderResult } from '@testing-library/react';
+import { ReactElement } from 'react';
+
+/**
+ * Returns the public key set that verifies the tokens `signTestToken` signs.
+ *
+ * @remarks
+ * The pair is generated once per process and cached, so every call in a suite
+ * returns the same set. Pass it as `jwks` to `createTappifyHandler` when a test
+ * drives the handler itself; `createTestClient` does that for you.
+ *
+ * @example
+ * ```ts
+ * import { createTappifyHandler } from '@tappify/extension-sdk/server';
+ * import { testJwks } from '@tappify/extension-sdk/testing';
+ *
+ * async function buildHandler() {
+ *   return createTappifyHandler({ extensionId: 'starter', jwks: await testJwks() });
+ * }
+ * ```
+ */
+declare function testJwks(): Promise<JSONWebKeySet>;
+/**
+ * Signs an install token a handler built against `testJwks` accepts.
+ *
+ * @remarks
+ * Every claim has a default — install `ins_test`, extension `starter`, project
+ * `prj_north`, organization `org_test`, no scopes — and the audience is
+ * `ext:<extensionId>`, taken from `options.extensionId`, then from the claims, then
+ * `starter`. It expires in five minutes unless `expiresIn` says otherwise, which is
+ * how a test covers an expired token. `createTestClient` and `createTapMock` sign
+ * their own tokens, so reach for this only when a test verifies a token itself.
+ *
+ * @example
+ * ```ts
+ * import { verifyTappifyToken } from '@tappify/extension-sdk/server';
+ * import { signTestToken, testJwks } from '@tappify/extension-sdk/testing';
+ *
+ * async function claimsOfTestToken() {
+ *   const token = await signTestToken({ scopes: ['analytics:read'] });
+ *   return verifyTappifyToken(token, {
+ *     extensionId: 'starter',
+ *     jwks: await testJwks(),
+ *   });
+ * }
+ * ```
+ */
+declare function signTestToken(claims?: Partial<TappifyClaims>, options?: {
+    extensionId?: string;
+    expiresIn?: string;
+}): Promise<string>;
+/** What every call a `TestClient` makes carries, unless a call overrides it. */
+interface TestClientDefaults {
+    /** Merged over the default install, whose id is `ins_test`. */
+    install?: Partial<TappifyInstall>;
+    /** The scopes the token claims. Defaults to none. */
+    scopes?: string[];
+    /** What the handler reads as `credentials`. Defaults to empty. */
+    credentials?: Record<string, unknown>;
+    /** What the handler reads as `documents`, including `settings`. */
+    documents?: Record<string, unknown>;
+    /** The filter bar behind the call. Defaults to a seven-day September range. */
+    filters?: TapFilters;
+    /** One fixed idempotency key. Left out, each call gets its own. */
+    eventId?: string;
+    /** The origin the request url is built on. Defaults to `https://vendor.test`. */
+    origin?: string;
+}
+/** One method per route Tappify calls, plus `raw` for the response itself. */
+interface TestClient {
+    /** Calls the health route, which carries no token. */
+    health(): Promise<TappifyHealth>;
+    /** Calls the connector's metrics route. */
+    metrics(input: MetricsInput): Promise<MetricsResponse>;
+    /** Calls one tool by id and returns the card it answered with. */
+    tool(id: string, input: unknown): Promise<unknown>;
+    /** Calls one mention by id, with the query as the `q` parameter. */
+    mention(id: string, query: string): Promise<MentionItems>;
+    /** Calls one action by id. */
+    action(id: string, input: unknown): Promise<unknown>;
+    /** Calls one procedure by name; the input defaults to an empty object. */
+    procedure(name: string, input?: unknown): Promise<unknown>;
+    /** Calls one context block by id. */
+    context(id: string): Promise<ContextBlock>;
+    /** Posts one Tappify event, which the handler answers with 204. */
+    event(name: string, payload: Record<string, unknown>): Promise<void>;
+    /** Calls one work operation. */
+    work(operation: WorkOperation, input: unknown): Promise<unknown>;
+    /**
+     * Sends any method and path and returns the `Response`, for a test that asserts
+     * on a status rather than a body.
+     */
+    raw(method: string, path: string, body?: unknown): Promise<Response>;
+}
+/**
+ * Drives a vendor server the way Tappify does, so a route is tested without a
+ * running Tappify.
+ *
+ * @remarks
+ * Pass the options object you hand `createTappifyHandler`, not the handler it
+ * returns: the client rebuilds the handler around `testJwks` and signs each call
+ * with a matching token. A built handler throws a `TapError` carrying
+ * `TAP_TEST_TARGET_INVALID`, because it would verify against the live Tappify key
+ * set and answer 401. Every call carries a fresh event id and the envelope Tappify
+ * sends, and every call but `health` a signed token, so the handler reads the same
+ * `install`, `context`, `credentials` and `documents` it will read in production. A route that
+ * answers an error rejects with a `TapServerError` carrying the code, message and
+ * status from the body, which is what a test asserts on; use `raw` when the status
+ * itself is the assertion. Every method calls the unprefixed path — `/tappify/…` —
+ * whatever `basePath` the options carry, so a `basePath` the handler strips off
+ * something else is not exercised here, and one that is itself a prefix of
+ * `/tappify`, such as `/tap`, makes every call 404 `TAP_ROUTE_UNKNOWN`. Reach a
+ * prefixed path through `raw` when that is what you need to cover.
+ *
+ * @example
+ * ```ts
+ * import type { TappifyHandlerOptions } from '@tappify/extension-sdk/server';
+ * import { createTestClient } from '@tappify/extension-sdk/testing';
+ * import { expect, it } from 'vitest';
+ *
+ * const handlerOptions: TappifyHandlerOptions = {
+ *   extensionId: 'starter',
+ *   health: () => ({ ok: true, version: '0.1.0' }),
+ * };
+ * const client = createTestClient(handlerOptions, { scopes: ['analytics:read'] });
+ *
+ * it('answers the health check', async () => {
+ *   await expect(client.health()).resolves.toEqual({ ok: true, version: '0.1.0' });
+ * });
+ * ```
+ */
+declare function createTestClient(target: TappifyHandlerOptions, defaults?: TestClientDefaults): TestClient;
+
+/**
+ * Sets the host's fifteen CSS variables on an element, so a component renders in
+ * a test the way it renders in the host.
+ *
+ * @remarks
+ * Sets the light values as inline custom properties, which inherit into everything
+ * below the element. The vitest and jest presets call it on
+ * `document.documentElement` for you, so call it yourself only in a test that
+ * renders outside `renderWithTap` or wants the variables on one subtree. It sets
+ * no dark values; drive the mode through `renderWithTap`'s `theme` option, which
+ * is what `useTapTheme` reads.
+ *
+ * @example
+ * ```ts
+ * import { installHostTheme } from '@tappify/extension-sdk/testing';
+ *
+ * function mountRoot(): HTMLElement {
+ *   const root = document.createElement('div');
+ *   installHostTheme(root);
+ *   document.body.append(root);
+ *   return root;
+ * }
+ * ```
+ */
+declare function installHostTheme(root: HTMLElement): void;
+
+/** The owner's two Northlight apps, one per platform. */
+declare const fixtureApps: TapApp[];
+/** Three shipped releases: two iOS versions and the Android build of the newer one. */
+declare const fixtureReleases: TapRelease[];
+/**
+ * Three tracked terms with positions, two on iOS and one on Android, scored on
+ * the host's 1 to 10 traffic scale.
+ */
+declare const fixtureKeywords: TapKeyword[];
+/** One store listing, for iOS in `en-US`. */
+declare const fixtureListings: TapListing[];
+/** The Northlight project, with `fixtureApps` and `fixtureReleases` under it. */
+declare const fixtureProject: TapProjectResult;
+/**
+ * Builds the seven-day series for one metric, over the first week of September
+ * 2026.
+ *
+ * @remarks
+ * The same seven values every call, so an assertion on a total or a peak is
+ * stable: downloads peak at 1,512 and `conversion_rate` comes back with unit
+ * `ratio` where the other three come back as `count`. The range in the query does
+ * not change the points, so a test that drives the filter bar asserts on the call,
+ * not on different numbers.
+ *
+ * @example
+ * ```ts
+ * import { fixtureSeries } from '@tappify/extension-sdk/testing';
+ *
+ * const downloads = fixtureSeries('downloads');
+ * const best = Math.max(...downloads.points.map(point => point.value));
+ * ```
+ */
+declare function fixtureSeries(metric: TapSeriesMetric): TapSeriesResult;
+/** Three reviews across three countries, averaging 3.7 stars, one already replied to. */
+declare const fixtureReviews: TapReviewsResult;
+/** A 99.42% crash-free user rate with two issues, both on build 118. */
+declare const fixtureCrashes: TapCrashesResult;
+/** 41,200 USD of recurring revenue, 18 refunds, and a seven-day series under it. */
+declare const fixtureRevenue: TapRevenueResult;
+/** The shape of `fixtures`: every sandbox fixture under one name. */
+interface TapFixtures {
+    project: TapProjectResult;
+    apps: TapApp[];
+    releases: TapRelease[];
+    keywords: TapKeyword[];
+    listings: TapListing[];
+    reviews: TapReviewsResult;
+    crashes: TapCrashesResult;
+    revenue: TapRevenueResult;
+    /** `fixtureSeries`, so a series is built per metric rather than held. */
+    series(metric: TapSeriesMetric): TapSeriesResult;
+}
+/**
+ * The sandbox data the mock bridge and the portal preview both answer with, so a
+ * component behaves the same in a test and in the preview.
+ *
+ * @remarks
+ * These are the same objects the `fixture*` exports hold, gathered under one name.
+ * `answerFixtureQuery` clones before it answers, but reading `fixtures` directly
+ * hands you the live object, so a test that sorts or splices one has to copy it
+ * first.
+ *
+ * @example
+ * ```ts
+ * import { fixtures } from '@tappify/extension-sdk/testing';
+ *
+ * const newest = [...fixtures.releases].sort((left, right) =>
+ *   right.version.localeCompare(left.version),
+ * )[0];
+ * ```
+ */
+declare const fixtures: TapFixtures;
+/**
+ * Answers one `tap.data.query` from the fixtures, which is what the mock bridge
+ * does.
+ *
+ * @remarks
+ * Every branch is cloned with `structuredClone`, so a component that sorts or
+ * splices a result cannot reach the fixture the next test reads. It checks no
+ * scope — `createTapMock` refuses an ungranted kind before it gets here — and it
+ * ignores the range and platform in the query, so the numbers are the same
+ * whatever the filter bar says. The seven assertions inside are the one place
+ * TypeScript cannot follow the distributive conditional in `TapResult<Q>` back
+ * through a `switch`; each branch returns exactly the result its `case` selected.
+ *
+ * @example
+ * ```ts
+ * import { answerFixtureQuery } from '@tappify/extension-sdk/testing';
+ *
+ * const reviews = answerFixtureQuery({
+ *   kind: 'reviews',
+ *   range: { from: '2026-09-01', to: '2026-09-08' },
+ * });
+ * const lowest = Math.min(...reviews.reviews.map(review => review.rating));
+ * ```
+ */
+declare function answerFixtureQuery<Q extends TapQuery>(query: Q): TapResult<Q>;
+
+/**
+ * Everything the component asked the host to do, in call order, for a test to
+ * assert on.
+ */
+interface TapMockCalls {
+    /** One entry per `tap.nav.push`. */
+    navigations: string[];
+    /** One entry per `tap.nav.setSearch`. */
+    searches: Record<string, string | null>[];
+    /** One entry per `tap.ui.toast`; the tone defaults to `neutral`. */
+    toasts: {
+        message: string;
+        tone: TapToastTone;
+    }[];
+    /** One entry per `tap.ui.confirm`, whatever the mock answered. */
+    confirms: TapConfirmOptions[];
+    /** One entry per `tap.actions.run`, which the mock records rather than refuses. */
+    actions: {
+        actionId: string;
+        input: unknown;
+    }[];
+    /** One entry per `tap.telemetry.event`. */
+    telemetry: {
+        name: string;
+        props?: Record<string, string | number | boolean>;
+    }[];
+    /** One entry per `tap.nav.openChat`. */
+    chats: {
+        prompt: string;
+        context?: Record<string, unknown>;
+    }[];
+    /** One url per `tap.nav.openExternal`, with no confirmation asked. */
+    externals: string[];
+    /** The filename and byte size per `tap.ui.download`, not the blob itself. */
+    downloads: {
+        filename: string;
+        size: number;
+    }[];
+    /** One entry per `tap.ui.copy`, with no clipboard touched. */
+    copies: string[];
+    /** One card per `tap.ui.openInChat`, unformatted. */
+    cards: TapChatCard[];
+    /** How many times `tap.ui.expand` was called. */
+    expands: number;
+    /** How many times `tap.nav.openSettings` was called. */
+    settingsOpens: number;
+}
+/**
+ * How the mock bridge is built, and the options `renderWithTap` forwards to it.
+ */
+interface CreateTapMockOptions {
+    /** Defaults to `ins_test`. */
+    installId?: string;
+    /** Defaults to `starter`, and has to match `handler`'s own extension id. */
+    extensionId?: string;
+    /** Defaults to `Starter`. */
+    extensionName?: string;
+    /** What the install granted. Defaults to every scope. */
+    scopes?: ScopeKey[];
+    /** What `tap.ui.size` reports. Defaults to `slot`. */
+    size?: TapSize;
+    /** Merged over the fixture filter bar. */
+    filters?: Partial<TapFilters>;
+    /** Merged over the fixture Northlight project. */
+    project?: Partial<Tap['project']>;
+    /** What `tap.context` holds. Defaults to empty. */
+    context?: Record<string, unknown>;
+    /** What `tap.params` holds, in the host's positional shape. Defaults to empty. */
+    params?: Record<string, string>;
+    /** What `useTapTheme` reports. Defaults to `light`. */
+    theme?: 'light' | 'dark';
+    /** What `tap.ui.confirm` resolves to. Defaults to `true`. */
+    confirmAnswer?: boolean;
+    /** The collections to expose, and the kind of each. Left out, every name works. */
+    storage?: Record<string, 'singleton' | 'collection'>;
+    /** One function per procedure, answering `tap.server.<name>` in process. */
+    server?: Record<string, (input: unknown) => unknown>;
+    /** Your own handler, so `tap.server.<name>` goes through its real routes. */
+    handler?: TappifyFetchHandler;
+    /** A token to send to `handler`. Defaults to one the mock signs itself. */
+    handlerToken?: string;
+}
+/** The mock bridge, with the recorded calls and the handles that drive it. */
+interface TapMock {
+    /** The bridge itself, which `renderWithTap` puts above the component. */
+    tap: Tap;
+    calls: TapMockCalls;
+    /** The node `TapDialog` renders into, appended to the document by `renderWithTap`. */
+    portal: HTMLElement;
+    /** What a collection holds now, or just the one document under `documentId`. */
+    documents(collection: string, documentId?: string): unknown[];
+    /** Delivers a Tappify event to everything subscribed through `tap.data.subscribe`. */
+    emit<E extends keyof TapHostEvents>(event: E, payload: TapHostEvents[E]): void;
+    /** Replaces the whole filter bar and re-renders the hooks that read it. */
+    setFilters(filters: TapFilters): void;
+    /** Moves the mount between slot, panel and page. */
+    setSize(size: TapSize): void;
+    /** Switches the theme `useTapTheme` reports. */
+    setTheme(mode: 'light' | 'dark'): void;
+    /** Replaces the route `useTapParams` reports, in the host's own positional shape. */
+    setParams(params: Record<string, string>): void;
+}
+/**
+ * Builds the bridge a component talks to in a test, without rendering anything.
+ *
+ * @remarks
+ * Data queries answer from the sandbox fixtures, storage is an in-memory store, and
+ * everything else the host would do is recorded in `calls`. Scopes default to all of
+ * them: pass `scopes` to test the refused path, where a data query rejects with
+ * `TAP_SCOPE_MISSING` for the kind's own scope and every storage call, reads
+ * included, needs `storage:write`. A procedure needs either `server`, which answers
+ * in process, or `handler`, which is called over a real `Request` with a token the
+ * mock signs — so that handler has to be built with `jwks: await testJwks()` and the
+ * same `extensionId` — and without either, `tap.server.<name>` rejects with
+ * `TAP_UNKNOWN_PROCEDURE`. With `storage` given, a collection the map does not name
+ * throws `TAP_UNKNOWN_COLLECTION`. Unlike the host, this mock records
+ * `tap.actions.run` and resolves it as pending rather than refusing it, so a test
+ * can assert on the call today. Use `renderWithTap` when there is a component to
+ * render.
+ *
+ * @example
+ * ```ts
+ * import { createTapMock } from '@tappify/extension-sdk/testing';
+ * import { expect, it } from 'vitest';
+ *
+ * it('answers a keyword query from the fixtures', async () => {
+ *   const mock = createTapMock({ scopes: ['store.metadata:read'] });
+ *   const keywords = await mock.tap.data.query({ kind: 'keywords' });
+ *   expect(keywords.keywords).toHaveLength(3);
+ * });
+ * ```
+ */
+declare function createTapMock(options?: CreateTapMockOptions): TapMock;
+
+/**
+ * What `renderWithTap` takes: its own three options, plus every
+ * `CreateTapMockOptions` member it forwards to the mock.
+ */
+interface RenderWithTapOptions extends CreateTapMockOptions {
+    /** A mock you built yourself. Given, every mock option here is ignored. */
+    mock?: TapMock;
+    /** Your own client, for a test that reads the cache. Defaults to a fresh one. */
+    queryClient?: QueryClient;
+    /** Passed to Testing Library's `render`, for a mount point of your own. */
+    container?: RenderOptions['container'];
+}
+/** What `renderWithTap` returns: Testing Library's result plus the bridge. */
+interface RenderWithTapResult extends RenderResult {
+    /** The same object `useTap` returns inside the component. */
+    tap: Tap;
+    /** The mock behind the bridge, which the matchers take. */
+    mock: TapMock;
+    /** The client the render used, whether it was passed in or built here. */
+    queryClient: QueryClient;
+}
+/**
+ * Renders a component against the mock bridge, so a widget, tab, page, row action
+ * or settings panel is testable outside Tappify.
+ *
+ * @remarks
+ * It builds a mock from the same options `createTapMock` takes unless you pass
+ * `mock`, wraps the component in the host provider and a `QueryClient` that does
+ * not retry and does not cache between tests, and appends the mock's portal to the
+ * rendered document so `TapDialog` has somewhere to go. It rewires
+ * `tap.invalidate` onto that client, so a component calling it drops the right
+ * cache entries. Scopes default to all of them, so pass `scopes` to cover the
+ * refused path; a `handler` has to be built with `jwks: await testJwks()` and the
+ * same `extensionId` the mock reports. Load
+ * `@tappify/extension-sdk/testing/vitest` or `.../testing/jest` as a setup file
+ * first: that installs the host CSS variables, registers the matchers and clears
+ * the portal between tests.
+ *
+ * @example
+ * ```tsx
+ * import { TapStat, useTapQuery } from '@tappify/extension-sdk';
+ * import { renderWithTap } from '@tappify/extension-sdk/testing';
+ * import { screen, waitFor } from '@testing-library/react';
+ * import { expect, it } from 'vitest';
+ *
+ * function Crashes() {
+ *   const crashes = useTapQuery({
+ *     kind: 'crashes',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   return <TapStat label="Issues" value={crashes.data?.issues.length ?? 0} />;
+ * }
+ *
+ * it('renders the issues the fixtures answer with', async () => {
+ *   renderWithTap(<Crashes />, { scopes: ['ui:render', 'crashes:read'] });
+ *   await waitFor(() => expect(screen.getByText('2')).toBeTruthy());
+ * });
+ * ```
+ */
+declare function renderWithTap(ui: ReactElement, options?: RenderWithTapOptions): RenderWithTapResult;
+
+/**
+ * Checks a metrics response against the metrics the manifest declares and returns
+ * what is wrong with it.
+ *
+ * @remarks
+ * Returns an empty array when the response is sound, so a test asserts on an empty
+ * list. It reports a body that is not `{ series: [...] }`, an entry with no
+ * `metric` key, a metric the declarations do not name, a unit that disagrees with
+ * the declared one, a missing `points` array, and any point that is not a
+ * `[string, number]` pair. It does not check that every declared metric is
+ * answered, so assert on the length yourself when that matters. The strings are the
+ * ones `tappify extension doctor` reports.
+ *
+ * @example
+ * ```ts
+ * import { validateMetricsResponse } from '@tappify/extension-sdk/testing';
+ * import { expect, it } from 'vitest';
+ *
+ * const metrics = [
+ *   { key: 'orders', label: 'Orders', unit: 'count' as const, kind: 'counter' as const },
+ * ];
+ *
+ * it('answers orders as a counted series', () => {
+ *   const response = { series: [{ metric: 'orders', unit: 'count', points: [['2026-09-01', 12]] }] };
+ *   expect(validateMetricsResponse(response, metrics)).toEqual([]);
+ * });
+ * ```
+ */
+declare function validateMetricsResponse(response: unknown, metrics: MetricDeclaration[]): string[];
+/**
+ * Checks a tool's answer against the card shape its declared `returns` kind has to
+ * carry, and returns what is missing.
+ *
+ * @remarks
+ * Returns an empty array when the answer is sound. A `value` card needs `label` and
+ * `value`, a `series` card `label` and `points`, a `table` card `columns` and
+ * `rows`, a `list` card `items`, and a `comparison` card `label`, `left` and
+ * `right`; anything that is not an object is reported on its own. It checks the
+ * keys are present, not what they hold, so an empty `rows` array passes.
+ *
+ * @example
+ * ```ts
+ * import { validateToolResponse } from '@tappify/extension-sdk/testing';
+ * import { expect, it } from 'vitest';
+ *
+ * it('answers keyword_gaps with a table card', () => {
+ *   const card = { columns: [{ key: 'term', label: 'Term' }], rows: [] };
+ *   expect(validateToolResponse(card, 'table')).toEqual([]);
+ * });
+ * ```
+ */
+declare function validateToolResponse(value: unknown, returns: ToolDeclaration['returns']): string[];
+
+export { type CreateTapMockOptions, type RenderWithTapOptions, type RenderWithTapResult, type TapFixtures, type TapMock, type TapMockCalls, type TestClient, type TestClientDefaults, answerFixtureQuery, createTapMock, createTestClient, fixtureApps, fixtureCrashes, fixtureKeywords, fixtureListings, fixtureProject, fixtureReleases, fixtureRevenue, fixtureReviews, fixtureSeries, fixtures, installHostTheme, renderWithTap, signTestToken, testJwks, validateMetricsResponse, validateToolResponse };