@tappify/extension-sdk 2.0.0

package/dist/codegen.d.ts

@@ -0,0 +1,432 @@
+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 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 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 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];
+
+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;
+}
+
+declare const GENERATED_HEADER = "/* eslint-disable */\n/**\n * Generated by `tappify extension types`. Do not edit by hand.\n * Re-run the command after changing tappify.extension.json or any schema it points at.\n */";
+interface RegistrySnapshot {
+    events: {
+        name: string;
+        payload?: JsonSchema;
+    }[];
+}
+interface GenerateTypesOptions {
+    manifest: ExtensionManifest;
+    registrySnapshot?: RegistrySnapshot;
+    readSchemaFile?(path: string): JsonSchema;
+    /**
+     * The extension root. A `$ref` inside a schema file resolves against that
+     * file's own directory under it, the way the host and the Tap Store read
+     * it; without a root the process directory stands in.
+     */
+    cwd?: string;
+}
+declare function generateTypes(options: GenerateTypesOptions): Promise<string>;
+
+export { GENERATED_HEADER, type GenerateTypesOptions, type RegistrySnapshot, generateTypes };

package/dist/codegen.mjs

@@ -0,0 +1,272 @@
+// src/codegen/generate.ts
+import { compile } from "json-schema-to-typescript";
+import { dirname, join } from "path";
+
+// src/client/errors.ts
+var TAP_ERROR_CODES = [
+  "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"
+];
+var CODE_SET = new Set(TAP_ERROR_CODES);
+var TapError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "TapError";
+    this.code = code;
+  }
+  /**
+   * Narrows an unknown value to a `TapError`, by name and by a code it
+   * recognises, so it holds across module instances.
+   */
+  static is(value) {
+    return value instanceof Error && value.name === "TapError" && "code" in value && typeof value.code === "string" && CODE_SET.has(value.code);
+  }
+};
+
+// src/codegen/generate.ts
+var GENERATED_HEADER = `/* 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.
+ */`;
+var STYLE = {
+  bracketSpacing: true,
+  printWidth: 80,
+  semi: true,
+  singleQuote: true,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false
+};
+function pascal(value) {
+  return value.split(/[^A-Za-z0-9]+/).filter((part) => part !== "").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function createEmitter(resolveSchema) {
+  const used = /* @__PURE__ */ new Set();
+  const blocks = [];
+  return {
+    async declare(preferredName, schema) {
+      let name = pascal(preferredName);
+      let suffix = 2;
+      while (used.has(name)) {
+        name = `${pascal(preferredName)}${String(suffix)}`;
+        suffix += 1;
+      }
+      used.add(name);
+      const resolved = resolveSchema(schema);
+      const input = {
+        ...resolved.schema,
+        title: name
+      };
+      const text = await compile(input, name, {
+        bannerComment: "",
+        additionalProperties: false,
+        declareExternallyReferenced: true,
+        enableConstEnums: false,
+        format: true,
+        style: STYLE,
+        unknownAny: true,
+        ...resolved.cwd === void 0 ? {} : { cwd: resolved.cwd }
+      });
+      blocks.push(text.trim());
+      return name;
+    },
+    declarations() {
+      return blocks;
+    }
+  };
+}
+function credentialSchema(fields) {
+  const properties = {};
+  const required = [];
+  for (const field of fields) {
+    const property = field.type === "select" && field.options ? { type: "string", enum: field.options } : { type: "string" };
+    if (field.help !== void 0) property.description = field.help;
+    properties[field.name] = property;
+    if (field.required) required.push(field.name);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+async function generateTypes(options) {
+  const { manifest, registrySnapshot } = options;
+  const contributes = manifest.contributes;
+  const resolveSchema = (schema) => {
+    const ref = schema.$ref;
+    if (typeof ref !== "string" || ref.startsWith("#")) {
+      return { schema, cwd: options.cwd };
+    }
+    if (options.readSchemaFile === void 0) {
+      throw new TapError(
+        "TAP_SCHEMA_UNRESOLVED",
+        `The manifest points at the schema file "${ref}", but this call passed no readSchemaFile. Run \`tappify extension types\`, which reads schema files from the extension directory, or supply readSchemaFile.`
+      );
+    }
+    return {
+      schema: options.readSchemaFile(ref),
+      cwd: options.cwd === void 0 ? void 0 : dirname(join(options.cwd, ref))
+    };
+  };
+  const emitter = createEmitter(resolveSchema);
+  const augmentations = [];
+  const storageEntries = Object.entries(contributes.storage ?? {});
+  if (storageEntries.length > 0) {
+    const lines = [];
+    for (const [name, collection] of storageEntries) {
+      const typeName = await emitter.declare(name, collection.schema);
+      const kind = collection.singleton === true ? "singleton" : "collection";
+      lines.push(
+        `    '${name}': { kind: '${kind}'; scope: '${collection.scope}'; document: ${typeName} };`
+      );
+    }
+    augmentations.push(`  interface TapStorageMap {
+${lines.join("\n")}
+  }`);
+  }
+  const procedureEntries = Object.entries(manifest.server?.procedures ?? {});
+  if (procedureEntries.length > 0) {
+    const lines = [];
+    for (const [name, declaration] of procedureEntries) {
+      const inputName = await emitter.declare(
+        `${name}Input`,
+        declaration.input
+      );
+      const outputName = await emitter.declare(
+        `${name}Output`,
+        declaration.output
+      );
+      lines.push(
+        `    '${name}': { input: ${inputName}; output: ${outputName} };`
+      );
+    }
+    augmentations.push(
+      `  interface TapProcedureMap {
+${lines.join("\n")}
+  }`
+    );
+  }
+  const actions = contributes.ai?.actions ?? [];
+  if (actions.length > 0) {
+    const lines = [];
+    for (const action of actions) {
+      const name = await emitter.declare(`${action.id}Input`, action.input);
+      lines.push(`    '${action.id}': { input: ${name} };`);
+    }
+    augmentations.push(`  interface TapActionMap {
+${lines.join("\n")}
+  }`);
+  }
+  const tools = contributes.ai?.tools ?? [];
+  if (tools.length > 0) {
+    const lines = [];
+    for (const tool of tools) {
+      const name = await emitter.declare(`${tool.id}Input`, tool.input);
+      lines.push(`    '${tool.id}': { input: ${name} };`);
+    }
+    augmentations.push(`  interface TapToolMap {
+${lines.join("\n")}
+  }`);
+  }
+  const prompts = (contributes.ai?.prompts ?? []).filter(
+    (prompt) => prompt.input !== void 0
+  );
+  if (prompts.length > 0) {
+    const lines = [];
+    for (const prompt of prompts) {
+      const name = await emitter.declare(
+        `${prompt.id}PromptInput`,
+        prompt.input ?? { type: "object" }
+      );
+      lines.push(`    '${prompt.id}': { input: ${name} };`);
+    }
+    augmentations.push(`  interface TapPromptMap {
+${lines.join("\n")}
+  }`);
+  }
+  const webhooks = contributes.webhooks ?? [];
+  if (webhooks.length > 0) {
+    const lines = [];
+    for (const webhook of webhooks) {
+      const name = await emitter.declare(
+        `${webhook.event}Payload`,
+        webhook.payload
+      );
+      lines.push(`    '${webhook.event}': ${name};`);
+    }
+    augmentations.push(`  interface TapWebhookMap {
+${lines.join("\n")}
+  }`);
+  }
+  if (registrySnapshot !== void 0 && registrySnapshot.events.length > 0) {
+    const lines = [];
+    for (const event of registrySnapshot.events) {
+      const name = await emitter.declare(
+        `${event.name}Event`,
+        event.payload ?? { type: "object" }
+      );
+      lines.push(`    '${event.name}': ${name};`);
+    }
+    augmentations.push(
+      `  interface TapHostEventMap {
+${lines.join("\n")}
+  }`
+    );
+  }
+  const telemetry = manifest.telemetry ?? [];
+  if (telemetry.length > 0) {
+    const lines = telemetry.map((name) => `    '${name}': true;`);
+    augmentations.push(
+      `  interface TapTelemetryEvents {
+${lines.join("\n")}
+  }`
+    );
+  }
+  if (contributes.settings) {
+    const name = await emitter.declare("Settings", contributes.settings.schema);
+    augmentations.push(`  interface TapSettings extends ${name} {}`);
+  }
+  const credentialFields = contributes.connector?.auth?.fields ?? [];
+  if (credentialFields.length > 0) {
+    const name = await emitter.declare(
+      "Credentials",
+      credentialSchema(credentialFields)
+    );
+    augmentations.push(`  interface TapCredentials extends ${name} {}`);
+  }
+  const declarations = emitter.declarations();
+  const module = augmentations.length === 0 ? "declare module '@tappify/extension-sdk' {}" : `declare module '@tappify/extension-sdk' {
+${augmentations.join("\n\n")}
+}`;
+  return [
+    GENERATED_HEADER,
+    "",
+    ...declarations.length > 0 ? [declarations.join("\n\n"), ""] : [],
+    module,
+    "",
+    "export {};",
+    ""
+  ].join("\n");
+}
+export {
+  GENERATED_HEADER,
+  generateTypes
+};
+//# sourceMappingURL=codegen.mjs.map