@tappify/extension-sdk 2.1.0-beta.2 → 2.1.0

package/dist/work-events-BlOVpK0k.d.ts

@@ -1,547 +0,0 @@
-import { JSONWebKeySet } from 'jose';
-import { K as TapPlatformFilter, a as TapFilters, w as TapCredentialValues, $ as TapSettingsValues, ab as ToolId, ac as ToolInput, A as ActionId, k as ActionInput, f as TapProcedureName, g as TapProcedureInput, h as TapProcedureOutput, c as TapHostEvents } from './types-uGHrRaOj.js';
-import { a9 as WorkContribution } from './constants-Bh759FUI.js';
-
-/** The provider stage used by the manifest's legacy status mapping. */
-type WorkStage = keyof NonNullable<NonNullable<WorkContribution['status']>['map']>;
-/** JSON-safe values supplied for provider create fields. */
-type WorkCreateFieldValues = Record<string, string | number | boolean | string[] | null>;
-/** Logical mutation identity, stable across transport retries. */
-interface WorkMutationInput {
-    idempotencyKey: string;
-    /** The source occurrence time as an ISO 8601 string. */
-    occurredAt: string;
-}
-/** A provider destination available to this install's credentials. */
-interface WorkContainer {
-    id: string;
-    label: string;
-    url?: string;
-    parentId?: string;
-}
-/** An exact provider status and its normalized Review stage. */
-interface WorkStatus {
-    id: string;
-    label: string;
-    /** Both open and in_progress represent an open Review thread. */
-    stage: WorkStage;
-}
-/** Provision or rotate the install's dedicated work-event callback. */
-interface WorkConfigureInput extends WorkMutationInput {
-    callbackUrl: string;
-    /** Store encrypted with the install's provider webhook routing record. */
-    secret: string;
-    generation: number;
-    configurationRevision: number;
-    containerId: string;
-    itemTypeId: string;
-    fields: WorkCreateFieldValues;
-    openStatusId: string;
-    resolvedStatusId: string;
-    commentsEnabled: boolean;
-}
-/** Callback generation acknowledged by the provider and its webhook registrations. */
-interface WorkConfigureResult {
-    generation: number;
-    configurationRevision: number;
-    registeredWebhookIds: string[];
-}
-/** Optional filters and pagination for destination discovery. */
-interface WorkListContainersInput {
-    /** Opaque provider pagination token; pass through unchanged. */
-    cursor?: string;
-    query?: string;
-    parentId?: string;
-}
-/** One page of available provider destinations. */
-interface WorkListContainersResult {
-    containers: WorkContainer[];
-    /** Omitted or null when no further page exists. */
-    cursor?: string | null;
-}
-/** The destination whose current workflow metadata the host needs. */
-interface WorkDescribeContainerInput {
-    containerId: string;
-}
-/** A selectable provider item type within a destination. */
-interface WorkItemType {
-    id: string;
-    label: string;
-}
-/** A create form field, including whether it is required and supported choices. */
-interface WorkCreateField {
-    id: string;
-    label: string;
-    type: 'string' | 'number' | 'boolean' | 'string[]';
-    required: boolean;
-    options?: {
-        value: string;
-        label: string;
-    }[];
-    /** Restrict a field to these item types, when workflows differ. */
-    itemTypeIds?: string[];
-}
-/** Current create requirements and exact statuses for one destination. */
-interface WorkDescribeContainerResult {
-    container: WorkContainer;
-    itemTypes: WorkItemType[];
-    createFields: WorkCreateField[];
-    statuses: WorkStatus[];
-}
-/** A short-lived screenshot URL; refreshed by the host for each retry. */
-interface ReviewImageAttachmentDescriptor {
-    kind: 'image';
-    attachmentId: string;
-    url: string;
-    mediaType: string;
-    fileName: string;
-}
-/** A Tappify deep link that can be attached independently of a screenshot. */
-interface ReviewLinkAttachmentDescriptor {
-    kind: 'link';
-    attachmentId: string;
-    url: string;
-    title?: string;
-}
-/** An image or link attached after the external item has been linked. */
-type ReviewAttachmentDescriptor = ReviewImageAttachmentDescriptor | ReviewLinkAttachmentDescriptor;
-/** Scope-approved snapshot used to create an item for a Review thread. */
-interface ReviewThreadSource {
-    threadId: string;
-    projectId: string;
-    appId: string;
-    buildVersion: string | null;
-    buildNumber: string | null;
-    screenId: string;
-    screenName?: string;
-    /** Coordinates normalized to the screen's width and height. */
-    pin: {
-        x: number;
-        y: number;
-    };
-    firstComment: {
-        id: string;
-        body: string;
-        authorDisplayName: string;
-        createdAt: string;
-    };
-    device: Record<string, string | number | boolean | null>;
-    deepLink: string;
-    screenshot?: ReviewImageAttachmentDescriptor;
-}
-/** Create one provider item from the Review snapshot and owner-selected fields. */
-interface WorkCreateInput extends WorkMutationInput {
-    containerId: string;
-    itemTypeId: string;
-    fields: WorkCreateFieldValues;
-    source: ReviewThreadSource;
-}
-/** Stable provider identity and display metadata persisted with the Review link. */
-interface WorkItemLinkResult {
-    externalItemId: string;
-    displayKey: string;
-    url: string;
-    title: string;
-    status: WorkStatus;
-    providerVersion?: string;
-    updatedAt?: string;
-}
-/** Identity carried on operations for an existing Review-to-provider link. */
-interface WorkLinkedItemInput {
-    linkId: string;
-    externalItemId: string;
-    threadId: string;
-}
-/** Attach one image or link without recreating the provider item. */
-interface WorkAttachInput extends WorkMutationInput, WorkLinkedItemInput {
-    attachment: ReviewAttachmentDescriptor;
-}
-/** The attachment identity when the provider exposes one. */
-interface WorkAttachResult {
-    externalAttachmentId?: string;
-}
-/** Append one Review comment to an existing provider item. */
-interface WorkCommentInput extends WorkMutationInput, WorkLinkedItemInput {
-    commentId: string;
-    body: string;
-    authorDisplayName: string;
-    createdAt: string;
-}
-/** Provider comment identity and time used to suppress webhook echoes. */
-interface WorkCommentResult {
-    externalCommentId: string;
-    createdAt: string;
-    providerVersion?: string;
-}
-/** Apply the owner's exact provider status for an open or resolved Review thread. */
-interface WorkSetStatusInput extends WorkMutationInput, WorkLinkedItemInput {
-    tappifyStatus: 'open' | 'resolved';
-    /** The exact provider target selected in destination configuration. */
-    providerStatusId: string;
-}
-/** Resulting provider status and optional version used to suppress webhook echoes. */
-interface WorkSetStatusResult {
-    status: WorkStatus;
-    providerVersion?: string;
-    updatedAt?: string;
-}
-/** Common identity for a fully hydrated provider signal. */
-interface WorkHydratedEventBase {
-    externalItemId: string;
-    providerEventId: string;
-    dedupeKey: string;
-    occurredAt: string;
-    providerVersion?: string;
-}
-/** A complete append-only provider comment signal. */
-interface WorkHydratedCommentCreatedEvent extends WorkHydratedEventBase {
-    type: 'comment.created';
-    comment: {
-        externalCommentId: string;
-        body: string;
-        author: {
-            id: string;
-            displayName: string;
-        };
-        createdAt: string;
-    };
-}
-/** A complete provider status-change signal. */
-interface WorkHydratedStatusChangedEvent extends WorkHydratedEventBase {
-    type: 'status.changed';
-    status: WorkStatus;
-}
-/** A provider item deletion signal. */
-interface WorkHydratedItemDeletedEvent extends WorkHydratedEventBase {
-    type: 'item.deleted';
-}
-/** Complete event content, with no opaque hydration reference remaining. */
-type WorkHydratedEvent = WorkHydratedCommentCreatedEvent | WorkHydratedStatusChangedEvent | WorkHydratedItemDeletedEvent;
-/** Resolve an opaque provider webhook reference using current install credentials. */
-interface WorkHydrateEventInput extends WorkLinkedItemInput {
-    hydrateRef: string;
-}
-/** Fully normalized content fetched for an opaque provider webhook reference. */
-interface WorkHydrateEventResult {
-    event: WorkHydratedEvent;
-}
-/** Clean up install-wide webhooks while provider credentials remain available. */
-interface WorkDisconnectInput extends WorkMutationInput {
-    generation: number;
-    registeredWebhookIds: string[];
-}
-/** Provider webhook registrations successfully removed during cleanup. */
-interface WorkDisconnectResult {
-    removedWebhookIds: string[];
-}
-/** Current host-to-extension work protocol. Legacy routes are excluded. */
-interface WorkOperationMap {
-    configure: {
-        input: WorkConfigureInput;
-        output: WorkConfigureResult;
-    };
-    list_containers: {
-        input: WorkListContainersInput;
-        output: WorkListContainersResult;
-    };
-    describe_container: {
-        input: WorkDescribeContainerInput;
-        output: WorkDescribeContainerResult;
-    };
-    create: {
-        input: WorkCreateInput;
-        output: WorkItemLinkResult;
-    };
-    attach: {
-        input: WorkAttachInput;
-        output: WorkAttachResult;
-    };
-    comment: {
-        input: WorkCommentInput;
-        output: WorkCommentResult;
-    };
-    set_status: {
-        input: WorkSetStatusInput;
-        output: WorkSetStatusResult;
-    };
-    hydrate_event: {
-        input: WorkHydrateEventInput;
-        output: WorkHydrateEventResult;
-    };
-    disconnect: {
-        input: WorkDisconnectInput;
-        output: WorkDisconnectResult;
-    };
-}
-
-/** Which install made the call, as the token's claims name it. */
-interface TappifyInstall {
-    /** The install id, which is the key to scope anything you store yourself by. */
-    id: string;
-    extensionId: string;
-    /** `null` for an install on the workspace rather than one project. */
-    projectId: string | null;
-    organizationId: string;
-}
-/** The project and the filter bar the call was made from. */
-interface TappifyCallContext {
-    projectId: string | null;
-    /** The same value as `filters.platform`, hoisted for convenience. */
-    platform: TapPlatformFilter;
-    /** The range start, as `YYYY-MM-DD`, or an empty string when none was sent. */
-    from: string;
-    /** The range end, as `YYYY-MM-DD`, or an empty string when none was sent. */
-    to: string;
-    filters: TapFilters;
-}
-/**
- * The install- and organization-scoped storage documents Tappify passes to the
- * server on every call, keyed by collection name.
- */
-type TappifyDocuments = Record<string, unknown> & {
-    /** The settings contribution's document, or `null` before it is first saved. */
-    settings?: TapSettingsValues | null;
-};
-/** The verified claims of an install token, as `verifyTappifyToken` returns them. */
-interface TappifyClaims {
-    iss: string;
-    /** Always `ext:<extensionId>`, which is what the verifier checked. */
-    aud: string;
-    exp: number;
-    iat: number;
-    installId: string;
-    extensionId: string;
-    projectId: string | null;
-    organizationId: string;
-    /** The scopes the install granted, as strings. */
-    scopes: string[];
-    /** Present when the token carries one, naming the teammate behind the call. */
-    userId?: string;
-}
-/** The single argument every route handler receives. */
-interface TappifyRequest<TInput = unknown, TEvent = unknown> {
-    install: TappifyInstall;
-    context: TappifyCallContext;
-    /**
-     * The call's `input`, or `{}` when the body carried none, and `undefined` on a
-     * context or events route, which take no input.
-     */
-    input: TInput;
-    credentials: TapCredentialValues;
-    documents: TappifyDocuments;
-    /** The event payload on an events route, and `undefined` on every other. */
-    event: TEvent | undefined;
-    /** The idempotency key from `X-Tappify-Event-Id`; deduplicate writes on it. */
-    eventId: string;
-    claims: TappifyClaims;
-    /** The original request, for a header or the raw body. */
-    request: Request;
-}
-/**
- * The signature every entry in `TappifyHandlerOptions` has: one argument, and a
- * value or a promise of one.
- */
-type TappifyRouteHandler<TInput = unknown, TOutput = unknown, TEvent = unknown> = (request: TappifyRequest<TInput, TEvent>) => TOutput | Promise<TOutput>;
-/** What the `GET /tappify/health` route answers with. */
-interface TappifyHealth {
-    /** Whether the server is ready to take calls; the publish check reads it. */
-    ok: boolean;
-    version?: string;
-    /** A line for the owner when the server is not ready. */
-    message?: string;
-}
-/** What Tappify asks a connector's metrics route for. */
-interface MetricsInput {
-    projectId: string | null;
-    platform: TapPlatformFilter;
-    /** The metric keys to answer for, from the ones the manifest declares. */
-    metrics: string[];
-    from: string;
-    to: string;
-}
-/** One metric's answer inside a `MetricsResponse`. */
-interface MetricsSeries {
-    /** The declared metric key this series answers for. */
-    metric: string;
-    /** Has to match the unit the manifest declares for that key. */
-    unit: 'count' | 'ratio' | 'currency' | 'seconds' | 'bytes';
-    /** One value per declared dimension, when the series is broken down. */
-    dimensions?: Record<string, string>;
-    /** `[timestamp, value]` pairs, oldest first. */
-    points: [string, number][];
-}
-/** What a connector's metrics route answers with: one series per asked metric. */
-interface MetricsResponse {
-    series: MetricsSeries[];
-}
-/** What a mention route answers with: the items the owner can pick from. */
-interface MentionItems {
-    items: {
-        id: string;
-        label: string;
-    }[];
-}
-/** What a context route answers with, for the owner's chat to read. */
-interface ContextBlock {
-    /** A line of prose the assistant can use as it is. */
-    summary: string;
-    /** The numbers behind the summary, for the assistant to quote. */
-    data?: Record<string, unknown>;
-}
-/** The work-tracker operations a handler's `work` table can answer. */
-type WorkOperation = keyof WorkOperationMap;
-/** SDK v2 compatibility routes, excluded from the current work protocol. */
-interface LegacyWorkHandlers {
-    /** @deprecated Implement set_status and use describe_container for status metadata. */
-    status?: TappifyRouteHandler<Record<string, unknown>, unknown>;
-    /** @deprecated Implement set_status to support both resolving and reopening. */
-    resolve?: TappifyRouteHandler<Record<string, unknown>, unknown>;
-}
-/** The second argument of `verifyTappifyToken`. */
-interface VerifyTokenOptions {
-    /** The `id` from the manifest; the token's audience has to be `ext:<id>`. */
-    extensionId: string;
-    /** Where to fetch the signing keys. Defaults to `DEFAULT_JWKS_URL`. */
-    jwksUrl?: string;
-    /** A key set to verify against, which skips the fetch. For tests. */
-    jwks?: JSONWebKeySet;
-}
-/**
- * The routes and settings `createTappifyHandler` builds a fetch handler from.
- *
- * @remarks
- * The `tools`, `actions` and `procedures` tables are keyed by the names the
- * augmentation `tappify extension types` writes, so a handler for an undeclared
- * name does not compile. `events` is keyed by Tappify's own event catalogue and
- * `work` by the fixed set of work operations; `mentions` and `context` take any id.
- * A route Tappify calls with no handler registered answers 404 with
- * `TAP_HANDLER_MISSING`. Export this object as well as the handler: the testing
- * entry's `createTestClient` takes the options, not the built handler.
- */
-interface TappifyHandlerOptions {
-    /** The `id` from the manifest, which the install token's audience has to match. */
-    extensionId: string;
-    /** Where to fetch the signing keys. Defaults to `DEFAULT_JWKS_URL`. */
-    jwksUrl?: string;
-    /** A key set to verify against, which skips the fetch. For tests. */
-    jwks?: JSONWebKeySet;
-    /** The prefix your framework mounts the handler under, such as `/api`. */
-    basePath?: string;
-    /** Answers `GET /tappify/health`. Left out, the route answers `{ ok: true }`. */
-    health?: () => TappifyHealth | Promise<TappifyHealth>;
-    /** Answers `POST /tappify/metrics` for a connector contribution. */
-    metrics?: TappifyRouteHandler<MetricsInput, MetricsResponse>;
-    /** One handler per declared tool, answering `POST /tappify/tools/<id>`. */
-    tools?: {
-        [T in ToolId]?: TappifyRouteHandler<ToolInput<T>, unknown>;
-    };
-    /** One handler per declared mention, answering `GET /tappify/mentions/<id>?q=`. */
-    mentions?: Record<string, TappifyRouteHandler<{
-        q: string;
-    }, MentionItems>>;
-    /** One handler per declared action, answering `POST /tappify/actions/<id>`. */
-    actions?: {
-        [A in ActionId]?: TappifyRouteHandler<ActionInput<A>, unknown>;
-    };
-    /** One handler per declared procedure, which is what `useTapServer` calls. */
-    procedures?: {
-        [N in TapProcedureName]?: TappifyRouteHandler<TapProcedureInput<N>, TapProcedureOutput<N>>;
-    };
-    /** One handler per declared context block, answering `GET /tappify/context/<id>`. */
-    context?: Record<string, TappifyRouteHandler<undefined, ContextBlock>>;
-    /** One handler per Tappify event you subscribe to; each answers 204. */
-    events?: {
-        [E in keyof TapHostEvents]?: TappifyRouteHandler<undefined, void, TapHostEvents[E]>;
-    };
-    /**
-     * One handler per work operation, answering `POST /tappify/work/<operation>`.
-     * If set_status is absent, a resolved target can invoke legacy resolve with
-     * id set to externalItemId. Its legacy result is returned unchanged; reopening
-     * needs set_status. Failures from a present set_status handler never fall back.
-     */
-    work?: {
-        [O in keyof WorkOperationMap]?: TappifyRouteHandler<WorkOperationMap[O]['input'], WorkOperationMap[O]['output']>;
-    } & LegacyWorkHandlers;
-}
-
-/**
- * What `createTappifyHandler` returns: a `fetch` handler, which is what Cloudflare
- * Workers, Vercel and the two adapters all take.
- */
-type TappifyFetchHandler = (request: Request) => Promise<Response>;
-/**
- * Builds the one `fetch` handler that answers every route Tappify calls on your
- * server.
- *
- * @remarks
- * It routes the paths under `/tappify`, minus `basePath` when your framework mounts
- * it under a prefix, and hands each matched handler a `TappifyRequest`. Every
- * route but `GET /tappify/health` needs a bearer install token, which it verifies
- * with `verifyTappifyToken`, and an `X-Tappify-Event-Id` header; a missing token is
- * 401 `TAP_TOKEN_MISSING`, a missing id 400 `TAP_EVENT_ID_MISSING`, an unknown path
- * 404 `TAP_ROUTE_UNKNOWN` and a declared name with no handler 404
- * `TAP_HANDLER_MISSING`. A body that is not JSON is 400 `TAP_BODY_INVALID` and one
- * over 1 MB is 413 `TAP_BODY_TOO_LARGE`. A `TapServerError` a handler throws is
- * answered with its own code and status, and a `TapError` other than the two token
- * failures with its own code and 400; anything else becomes 500
- * `TAP_INTERNAL_ERROR` with a fixed message, so an internal failure never reaches
- * the owner. An events route answers 204 with no body, and every other route
- * answers the handler's return value as JSON. Export the options object as well as
- * the handler: `createTestClient` takes the options.
- *
- * @example
- * ```ts
- * import {
- *   createTappifyHandler,
- *   type TappifyHandlerOptions,
- * } from '@tappify/extension-sdk/server';
- *
- * const handlerOptions: TappifyHandlerOptions = {
- *   extensionId: 'starter',
- *   health: () => ({ ok: true, version: '0.1.0' }),
- *   procedures: {
- *     getSummary: () => ({ installs: 1260, delta: 0.087, topKeyword: 'photo editor' }),
- *   },
- * };
- *
- * const handler = createTappifyHandler(handlerOptions);
- * ```
- */
-declare function createTappifyHandler(options: TappifyHandlerOptions): TappifyFetchHandler;
-
-/** An opaque provider signal to hydrate using current install credentials. */
-interface WorkHydrationReferenceEvent extends WorkHydratedEventBase {
-    type: WorkHydratedEvent['type'];
-    /** A nonempty, short-lived reference resolved by the hydrate_event handler. */
-    hydrateRef: string;
-    /** Normalized comment content must not accompany a reference. */
-    comment?: never;
-    /** Normalized status content must not accompany a reference. */
-    status?: never;
-}
-/** Complete normalized content or an opaque reference, with stable retry identity. */
-type WorkEvent = (WorkHydratedEvent & {
-    hydrateRef?: never;
-}) | WorkHydrationReferenceEvent;
-/** Install-specific delivery values provisioned through work configure. */
-interface SendWorkEventOptions {
-    /** The exact provisioned callback URL; no production default is supplied. */
-    callbackUrl: string;
-    /** The per-install work-event signing secret provisioned with the callback. */
-    secret: string;
-    /** A transport for tests or a proxy; defaults to global fetch. */
-    fetch?: typeof fetch;
-}
-/**
- * Sends one provider work event to the callback provisioned for this install.
- *
- * @remarks
- * Pass the callbackUrl and secret received through configure unchanged. The
- * event's required dedupeKey identifies the logical provider signal and must be
- * reused on retries. Complete normalized content and an opaque hydrateRef are
- * mutually exclusive. The exact serialized UTF-8 body is signed with HMAC-SHA-256.
- * This callback is independent of declared alert and banner webhooks.
- */
-declare function sendWorkEvent(event: WorkEvent, options: SendWorkEventOptions): Promise<void>;
-
-export { type WorkSetStatusResult as $, type WorkDisconnectResult as A, type WorkEvent as B, type ContextBlock as C, type WorkHydrateEventInput as D, type WorkHydrateEventResult as E, type WorkHydratedCommentCreatedEvent as F, type WorkHydratedEvent as G, type WorkHydratedEventBase as H, type WorkHydratedItemDeletedEvent as I, type WorkHydratedStatusChangedEvent as J, type WorkHydrationReferenceEvent as K, type LegacyWorkHandlers as L, type MentionItems as M, type WorkItemLinkResult as N, type WorkItemType as O, type WorkLinkedItemInput as P, type WorkListContainersInput as Q, type ReviewAttachmentDescriptor as R, type SendWorkEventOptions as S, type TappifyFetchHandler as T, type WorkListContainersResult as U, type VerifyTokenOptions as V, type WorkAttachInput as W, type WorkMutationInput as X, type WorkOperation as Y, type WorkOperationMap as Z, type WorkSetStatusInput as _, type TappifyClaims as a, type WorkStage as a0, type WorkStatus as a1, createTappifyHandler as a2, sendWorkEvent as a3, type MetricsInput as b, type MetricsResponse as c, type MetricsSeries as d, type ReviewImageAttachmentDescriptor as e, type ReviewLinkAttachmentDescriptor as f, type ReviewThreadSource as g, type TappifyCallContext as h, type TappifyDocuments as i, type TappifyHandlerOptions as j, type TappifyHealth as k, type TappifyInstall as l, type TappifyRequest as m, type TappifyRouteHandler as n, type WorkAttachResult as o, type WorkCommentInput as p, type WorkCommentResult as q, type WorkConfigureInput as r, type WorkConfigureResult as s, type WorkContainer as t, type WorkCreateField as u, type WorkCreateFieldValues as v, type WorkCreateInput as w, type WorkDescribeContainerInput as x, type WorkDescribeContainerResult as y, type WorkDisconnectInput as z };