@tappify/cli 1.3.2 → 1.5.0

package/templates/starter/api/tappify/[...path].ts

@@ -0,0 +1,6 @@
+import { createTappifyHandler } from '@tappify/extension-sdk/server';
+import { handlerOptions } from '../../server/handler';
+
+export const config = { runtime: 'edge' };
+
+export default createTappifyHandler({ ...handlerOptions, basePath: '/api' });

package/templates/starter/gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+coverage
+.wrangler
+.vercel
+*.tgz

package/templates/starter/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="__title__">
+  <rect width="32" height="32" rx="7" fill="#4f46e5" />
+  <path d="M9 21V15M16 21V11M23 21V17" stroke="#ffffff" stroke-width="3" stroke-linecap="round" />
+</svg>

package/templates/starter/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "__id__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "__description__",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "types": "tappify extension types",
+    "dev:worker": "wrangler dev",
+    "deploy:worker": "wrangler deploy"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.100.14",
+    "@tappify/extension-sdk": "^2.0.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "devDependencies": {
+    "@module-federation/vite": "~1.16.0",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "happy-dom": "^17.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.0.0"
+  }
+}

package/templates/starter/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  workerd: true

package/templates/starter/schemas/get-summary.input.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "GetSummaryInput",
+  "type": "object",
+  "properties": {
+    "days": { "type": "number" },
+    "platform": { "type": "string", "enum": ["ios", "android", "all"] }
+  },
+  "required": ["days", "platform"],
+  "additionalProperties": false
+}

package/templates/starter/schemas/get-summary.output.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "GetSummaryOutput",
+  "type": "object",
+  "properties": {
+    "installs": { "type": "number" },
+    "delta": { "type": "number" },
+    "topKeyword": { "type": "string" }
+  },
+  "required": ["installs", "delta"],
+  "additionalProperties": false
+}

package/templates/starter/schemas/preferences.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Preferences",
+  "type": "object",
+  "properties": {
+    "compact": {
+      "type": "boolean",
+      "description": "Render the summary on one line"
+    },
+    "metric": {
+      "type": "string",
+      "enum": ["downloads", "impressions"],
+      "description": "Which series the summary reports"
+    }
+  },
+  "required": ["compact", "metric"],
+  "additionalProperties": false
+}

package/templates/starter/schemas/settings.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Settings",
+  "type": "object",
+  "properties": {
+    "refreshMinutes": {
+      "type": "number",
+      "title": "Refresh minutes",
+      "description": "How often the summary asks the server for new numbers"
+    },
+    "showDelta": {
+      "type": "boolean",
+      "title": "Show change",
+      "description": "Show the change against the previous period"
+    }
+  },
+  "required": ["refreshMinutes"],
+  "additionalProperties": false
+}

package/templates/starter/server/actions/index.ts

@@ -0,0 +1 @@
+export const actions = {};

package/templates/starter/server/context/index.ts

@@ -0,0 +1 @@
+export const context = {};

package/templates/starter/server/handler.ts

@@ -0,0 +1,25 @@
+import {
+  createTappifyHandler,
+  type TappifyFetchHandler,
+  type TappifyHandlerOptions,
+} from '@tappify/extension-sdk/server';
+import { actions } from './actions';
+import { context } from './context';
+import { mentions } from './mentions';
+import { procedures } from './procedures';
+import { tools } from './tools';
+
+export const handlerOptions: TappifyHandlerOptions = {
+  extensionId: '__id__',
+
+  health: () => ({ ok: true, version: '0.1.0' }),
+
+  procedures,
+  tools,
+  actions,
+  mentions,
+  context,
+};
+
+export const handler: TappifyFetchHandler =
+  createTappifyHandler(handlerOptions);

package/templates/starter/server/mentions/index.ts

@@ -0,0 +1 @@
+export const mentions = {};

package/templates/starter/server/procedures/get-summary.ts

@@ -0,0 +1,32 @@
+import type {
+  TapProcedureInput,
+  TapProcedureOutput,
+} from '@tappify/extension-sdk';
+import { TapServerError } from '@tappify/extension-sdk/server';
+import type { TappifyRequest } from '@tappify/extension-sdk/server';
+
+const BASELINE_INSTALLS_PER_DAY = 180;
+
+export function getSummary(
+  request: TappifyRequest<TapProcedureInput<'getSummary'>>,
+): TapProcedureOutput<'getSummary'> {
+  const { days, platform } = request.input;
+
+  if (days < 1) {
+    throw new TapServerError(
+      'RANGE_TOO_SHORT',
+      'getSummary needs a range of at least one day. Widen the date picker, then retry.',
+      400,
+    );
+  }
+
+  const multiplier = platform === 'all' ? 1 : 0.55;
+  const installs = Math.round(BASELINE_INSTALLS_PER_DAY * days * multiplier);
+  const previous = Math.round(installs * 0.92);
+
+  return {
+    installs,
+    delta: (installs - previous) / previous,
+    topKeyword: 'photo editor',
+  };
+}

package/templates/starter/server/procedures/index.ts

@@ -0,0 +1,5 @@
+import { getSummary } from './get-summary';
+
+export const procedures = {
+  getSummary,
+};

package/templates/starter/server/tools/index.ts

@@ -0,0 +1 @@
+export const tools = {};

package/templates/starter/server/worker.ts

@@ -0,0 +1,5 @@
+import { handler } from './handler';
+
+export default {
+  fetch: handler,
+};

package/templates/starter/src/settings.tsx

@@ -0,0 +1,24 @@
+import {
+  TapForm,
+  TapPageHeader,
+  type TapSettingsProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+import schema from '../schemas/settings.json';
+
+export default function Settings({ values, onChange }: TapSettingsProps) {
+  return (
+    <div className="tap-stack">
+      <TapPageHeader
+        title="__title__"
+        description="These values reach your server as documents.settings on every call."
+      />
+      <TapForm
+        schema={schema}
+        value={values}
+        submitLabel="Save"
+        onSubmit={next => onChange(next)}
+      />
+    </div>
+  );
+}

package/templates/starter/src/styles.css

@@ -0,0 +1,16 @@
+.starter-summary {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.starter-summary--compact {
+  flex-direction: row;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.starter-summary__footnote {
+  color: var(--fg-muted, rgba(18, 18, 18, 0.6));
+  font-size: 11px;
+}

package/templates/starter/src/tappify.d.ts

@@ -0,0 +1,59 @@
+/* eslint-disable */
+/**
+ * Generated by `tappify extension types`. Do not edit by hand.
+ * Re-run the command after changing tappify.extension.json or any schema it points at.
+ */
+
+export interface Preferences {
+  /**
+   * Render the summary on one line
+   */
+  compact: boolean;
+  /**
+   * Which series the summary reports
+   */
+  metric: 'downloads' | 'impressions';
+}
+
+export interface GetSummaryInput {
+  days: number;
+  platform: 'ios' | 'android' | 'all';
+}
+
+export interface GetSummaryOutput {
+  installs: number;
+  delta: number;
+  topKeyword?: string;
+}
+
+/**
+ * How often the summary asks the server for new numbers
+ */
+export type RefreshMinutes = number;
+/**
+ * Show the change against the previous period
+ */
+export type ShowChange = boolean;
+
+export interface Settings {
+  refreshMinutes: RefreshMinutes;
+  showDelta?: ShowChange;
+}
+
+declare module '@tappify/extension-sdk' {
+  interface TapStorageMap {
+    'preferences': { kind: 'singleton'; scope: 'user'; document: Preferences };
+  }
+
+  interface TapProcedureMap {
+    'getSummary': { input: GetSummaryInput; output: GetSummaryOutput };
+  }
+
+  interface TapTelemetryEvents {
+    'summary_viewed': true;
+  }
+
+  interface TapSettings extends Settings {}
+}
+
+export {};

package/templates/starter/src/widgets/summary.tsx

@@ -0,0 +1,122 @@
+import {
+  TapButton,
+  TapCard,
+  TapErrorState,
+  TapSkeleton,
+  TapStat,
+  cn,
+  useTap,
+  useTapFilters,
+  useTapQuery,
+  useTapServer,
+  useTapStorage,
+  type TapSeriesPoint,
+  type TapWidgetProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+import { useEffect } from 'react';
+import '../styles.css';
+
+function daysBetween(from: string, to: string): number {
+  const start = new Date(from).getTime();
+  const end = new Date(to).getTime();
+  return Math.max(1, Math.round((end - start) / 86_400_000));
+}
+
+function bestDay(points: TapSeriesPoint[]): number {
+  return points.reduce((highest, point) => Math.max(highest, point.value), 0);
+}
+
+export default function Summary(_props: TapWidgetProps) {
+  const tap = useTap();
+  const filters = useTapFilters();
+  const preferences = useTapStorage('preferences');
+
+  const downloads = useTapQuery({
+    kind: 'series',
+    metric: 'downloads',
+    range: filters.range,
+  });
+
+  const summary = useTapServer(
+    'getSummary',
+    {
+      days: daysBetween(filters.range.from, filters.range.to),
+      platform: filters.platform,
+    },
+    { invalidateOn: ['settings.changed'] },
+  );
+
+  const refetchSummary = summary.refetch;
+
+  useEffect(() => {
+    return tap.data.subscribe('release.shipped', () => {
+      tap.ui.toast('A release shipped — refreshing the summary.', 'neutral');
+      refetchSummary();
+    });
+  }, [tap, refetchSummary]);
+
+  useEffect(() => {
+    tap.telemetry.event('summary_viewed', { size: tap.ui.size });
+  }, [tap]);
+
+  const compact = preferences.data?.compact ?? false;
+  const failure = summary.error ?? downloads.error;
+
+  return (
+    <TapCard
+      title="Install summary"
+      action={
+        <TapButton
+          variant="ghost"
+          size="sm"
+          onClick={() => void preferences.patch({ compact: !compact })}
+        >
+          {compact ? 'Expand' : 'Compact'}
+        </TapButton>
+      }
+      footer={
+        <span className="starter-summary__footnote">
+          {tap.format.date(filters.range.from)} to{' '}
+          {tap.format.date(filters.range.to)}
+        </span>
+      }
+    >
+      {(summary.isLoading || downloads.isLoading) && <TapSkeleton lines={2} />}
+
+      {failure !== null && (
+        <TapErrorState
+          title="The summary did not load"
+          description={failure.message}
+          onRetry={() => {
+            summary.refetch();
+            downloads.refetch();
+          }}
+        />
+      )}
+
+      {failure === null && summary.data !== undefined && (
+        <div
+          className={cn('starter-summary', compact && 'starter-summary--compact')}
+        >
+          <TapStat
+            label="Installs"
+            value={tap.format.number(summary.data.installs)}
+            delta={summary.data.delta}
+          />
+          {downloads.data !== undefined && (
+            <span className="starter-summary__footnote">
+              Best day: {tap.format.number(bestDay(downloads.data.points))}{' '}
+              downloads
+            </span>
+          )}
+          {summary.data.topKeyword !== undefined && (
+            <span className="starter-summary__footnote">
+              Top keyword: {summary.data.topKeyword}
+            </span>
+          )}
+        </div>
+      )}
+    </TapCard>
+  );
+}

package/templates/starter/tappify.extension.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://schema.tappify.ai/extension/v2.json",
+  "id": "__id__",
+  "name": "__title__",
+  "description": "__description__",
+  "icon": "icon.svg",
+  "category": "product_analytics",
+  "sdk": "^2.0.0",
+  "visibility": "private",
+  "installScope": "project",
+  "scopes": [
+    {
+      "key": "ui:render"
+    },
+    {
+      "key": "analytics:read"
+    },
+    {
+      "key": "storage:write"
+    }
+  ],
+  "telemetry": [
+    "summary_viewed"
+  ],
+  "contributes": {
+    "widgets": [
+      {
+        "id": "summary",
+        "title": "Install summary",
+        "entry": "src/widgets/summary.tsx",
+        "page": "analytics",
+        "slot": "kpi-row",
+        "size": "1x1",
+        "expandable": true
+      }
+    ],
+    "settings": {
+      "entry": "src/settings.tsx",
+      "schema": {
+        "$ref": "./schemas/settings.json"
+      }
+    },
+    "storage": {
+      "preferences": {
+        "scope": "user",
+        "singleton": true,
+        "schema": {
+          "$ref": "./schemas/preferences.json"
+        }
+      }
+    }
+  },
+  "server": {
+    "baseUrl": "https://__id__.example.com",
+    "procedures": {
+      "getSummary": {
+        "input": {
+          "$ref": "./schemas/get-summary.input.json"
+        },
+        "output": {
+          "$ref": "./schemas/get-summary.output.json"
+        },
+        "cache": "5m",
+        "kind": "read"
+      }
+    }
+  }
+}

package/templates/starter/test/matchers.d.ts

@@ -0,0 +1,2 @@
+import '@tappify/extension-sdk/testing/vitest';
+import '@testing-library/jest-dom/vitest';

package/templates/starter/test/server.test.ts

@@ -0,0 +1,69 @@
+import { createTestClient } from '@tappify/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { handlerOptions } from '../server/handler';
+
+const client = createTestClient(handlerOptions);
+const vercelClient = createTestClient({ ...handlerOptions, basePath: '/api' });
+
+describe('the extension server', () => {
+  it('answers the publish health check', async () => {
+    await expect(client.health()).resolves.toEqual({
+      ok: true,
+      version: '0.1.0',
+    });
+  });
+
+  it('answers getSummary with the declared output shape', async () => {
+    const summary = await client.procedure('getSummary', {
+      days: 7,
+      platform: 'all',
+    });
+
+    expect(summary).toMatchObject({
+      installs: expect.any(Number),
+      delta: expect.any(Number),
+      topKeyword: 'photo editor',
+    });
+  });
+
+  it('scales the answer with the platform filter', async () => {
+    const all = await client.procedure('getSummary', {
+      days: 7,
+      platform: 'all',
+    });
+    const ios = await client.procedure('getSummary', {
+      days: 7,
+      platform: 'ios',
+    });
+
+    expect(all).toMatchObject({ installs: 1260 });
+    expect(ios).toMatchObject({ installs: 693 });
+  });
+
+  it('returns a coded error a widget can show', async () => {
+    await expect(
+      client.procedure('getSummary', { days: 0, platform: 'all' }),
+    ).rejects.toMatchObject({
+      code: 'RANGE_TOO_SHORT',
+      status: 400,
+      message:
+        'getSummary needs a range of at least one day. Widen the date picker, then retry.',
+    });
+  });
+
+  it('404s a procedure the manifest does not declare', async () => {
+    const response = await client.raw('POST', '/tappify/procedures/ghost', {});
+
+    expect(response.status).toBe(404);
+  });
+
+  it('answers under the /api prefix the Vercel function is mounted at', async () => {
+    await expect(vercelClient.health()).resolves.toEqual({
+      ok: true,
+      version: '0.1.0',
+    });
+
+    const response = await vercelClient.raw('GET', '/api/tappify/health');
+    expect(response.status).toBe(200);
+  });
+});

package/templates/starter/test/settings.test.tsx

@@ -0,0 +1,46 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import Settings from '../src/settings';
+
+describe('the settings panel', () => {
+  it('renders one control per schema field', () => {
+    renderWithTap(
+      <Settings values={{ refreshMinutes: 15 }} onChange={vi.fn()} />,
+    );
+
+    expect(screen.getByLabelText('Refresh minutes')).toHaveValue(15);
+    expect(screen.getByLabelText('Show change')).toBeInTheDocument();
+  });
+
+  it('reports the new values on save', async () => {
+    const onChange = vi.fn();
+    renderWithTap(
+      <Settings values={{ refreshMinutes: 15 }} onChange={onChange} />,
+    );
+
+    await userEvent.clear(screen.getByLabelText('Refresh minutes'));
+    await userEvent.type(screen.getByLabelText('Refresh minutes'), '30');
+    await userEvent.click(screen.getByLabelText('Show change'));
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+    expect(onChange).toHaveBeenCalledWith({
+      refreshMinutes: 30,
+      showDelta: true,
+    });
+  });
+
+  it('refuses to save when a required value is missing', async () => {
+    const onChange = vi.fn();
+    renderWithTap(
+      <Settings values={{ refreshMinutes: 15 }} onChange={onChange} />,
+    );
+
+    await userEvent.clear(screen.getByLabelText('Refresh minutes'));
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+    expect(screen.getByText('Refresh minutes is required.')).toBeInTheDocument();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});