@tappify/extension-sdk 2.0.0

package/dist/server.d.cts

@@ -0,0 +1,243 @@
+export { c as TapServerError } from './errors-COsBh7kd.cjs';
+import { ad as WebhookName, ae as WebhookPayload } from './types-DrpQSv_2.cjs';
+export { A as ActionId, k as ActionInput, w as TapCredentialValues, a as TapFilters, c as TapHostEvents, $ as TapSettingsValues, ab as ToolId, ac as ToolInput } from './types-DrpQSv_2.cjs';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { T as TappifyFetchHandler, V as VerifyTokenOptions, a as TappifyClaims } from './handler-kU9Jf36K.cjs';
+export { C as ContextBlock, M as MentionItems, b as MetricsInput, c as MetricsResponse, d as MetricsSeries, e as TappifyCallContext, f as TappifyDocuments, g as TappifyHandlerOptions, h as TappifyHealth, i as TappifyInstall, j as TappifyRequest, k as TappifyRouteHandler, W as WorkOperation, l as createTappifyHandler } from './handler-kU9Jf36K.cjs';
+import './constants-DJ_KgZpN.cjs';
+import 'jose';
+
+/**
+ * The part of a Node readable stream the adapters use, so neither adapter has to
+ * name a framework's own request type.
+ */
+interface BodyStream {
+    /** Each chunk of the body, in order. */
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    /** The body is complete. */
+    on(event: 'end', listener: () => void): unknown;
+    /** The stream failed; the adapter rejects with the error. */
+    on(event: 'error', listener: (error: Error) => void): unknown;
+}
+/** The part of an Express request `toExpress` reads. */
+interface ExpressLikeRequest {
+    method: string;
+    /** Preferred over `url`, so a router-mounted path keeps its prefix. */
+    originalUrl?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** A parsed body from `express.json()`, or a raw string. */
+    body?: unknown;
+    /** Used as the scheme of the url handed to the handler. Defaults to `https`. */
+    protocol?: string;
+    /** Present when no parser has consumed the stream, which is then read as-is. */
+    on?: BodyStream['on'];
+}
+/** The part of an Express response `toExpress` writes. */
+interface ExpressLikeResponse {
+    /** Sets the status and returns the response, so the call chains into `send`. */
+    status(code: number): ExpressLikeResponse;
+    /** Called once per header the handler's response carries. */
+    setHeader(name: string, value: string): void;
+    /** Called once, with the handler's response body as text. */
+    send(body: string): void;
+}
+/** What `toExpress` returns: an Express middleware over the three arguments. */
+type ExpressMiddleware = (request: ExpressLikeRequest, response: ExpressLikeResponse, next: (error?: unknown) => void) => void;
+/** What `toNode` returns: a listener for `http.createServer`. */
+type NodeRequestListener = (request: IncomingMessage, response: ServerResponse) => void;
+/**
+ * Wraps the handler as Express middleware, for a server that speaks Express
+ * rather than `fetch`.
+ *
+ * @remarks
+ * It builds the url from `originalUrl` and the `host` header, forwards every
+ * header, and takes the body from `request.body` when a parser has already read
+ * it or from the stream when none has. A request with neither — a parser that
+ * consumed the stream without leaving a body — fails with a `TapServerError`
+ * carrying `TAP_BODY_INVALID` rather than calling your handler against an empty
+ * body, so mount `express.json()` before this middleware or mount this one first.
+ * A `TapServerError` is written as the handler's own JSON error; anything else
+ * goes to `next`, so your own error middleware sees it.
+ *
+ * @example
+ * ```ts
+ * import { createTappifyHandler, toExpress } from '@tappify/extension-sdk/server';
+ *
+ * const middleware = toExpress(
+ *   createTappifyHandler({ extensionId: 'starter', health: () => ({ ok: true }) }),
+ * );
+ * ```
+ */
+declare function toExpress(handler: TappifyFetchHandler): ExpressMiddleware;
+/**
+ * Wraps the handler as a listener for Node's own `http.createServer`, with no
+ * framework in between.
+ *
+ * @remarks
+ * It builds the url from `request.url` and the `host` header over `http`, forwards
+ * every header, and reads the body straight off the stream, so nothing may have
+ * consumed it first. It answers the whole response itself: a `TapServerError`
+ * becomes its own code and status, and anything else becomes 500
+ * `TAP_INTERNAL_ERROR`. Put it behind a TLS-terminating proxy in production; the
+ * scheme it builds is only what the handler sees in `request.url`.
+ *
+ * @example
+ * ```ts
+ * import { createTappifyHandler, toNode } from '@tappify/extension-sdk/server';
+ * import { createServer } from 'node:http';
+ *
+ * const listener = toNode(
+ *   createTappifyHandler({ extensionId: 'starter', health: () => ({ ok: true }) }),
+ * );
+ * const server = createServer(listener);
+ * ```
+ */
+declare function toNode(handler: TappifyFetchHandler): NodeRequestListener;
+
+/**
+ * The codes `createTappifyHandler` answers with itself, keyed by a short name.
+ *
+ * @remarks
+ * Every one of these comes from the SDK, not from your own handlers: a route or
+ * handler that is not there, a token that is missing or does not verify, a missing
+ * event id, a body that is not JSON or is over 1 MB, a webhook Tappify rejected,
+ * and the catch-all for an error a handler let escape. Throw a `TapServerError`
+ * with a code of your own for anything your server decides.
+ */
+declare const SERVER_ERROR_CODES: {
+    readonly ROUTE_UNKNOWN: "TAP_ROUTE_UNKNOWN";
+    readonly HANDLER_MISSING: "TAP_HANDLER_MISSING";
+    readonly INTERNAL_ERROR: "TAP_INTERNAL_ERROR";
+    readonly TOKEN_MISSING: "TAP_TOKEN_MISSING";
+    readonly TOKEN_INVALID: "TAP_TOKEN_INVALID";
+    readonly TOKEN_AUDIENCE: "TAP_TOKEN_AUDIENCE";
+    readonly EVENT_ID_MISSING: "TAP_EVENT_ID_MISSING";
+    readonly BODY_INVALID: "TAP_BODY_INVALID";
+    readonly BODY_TOO_LARGE: "TAP_BODY_TOO_LARGE";
+    readonly WEBHOOK_REJECTED: "TAP_WEBHOOK_REJECTED";
+};
+/** Every code the handler answers with itself, as a union of its own values. */
+type TapServerErrorCode = (typeof SERVER_ERROR_CODES)[keyof typeof SERVER_ERROR_CODES];
+
+/** The body `sendEvent` posts to Tappify, and the body the signature covers. */
+interface WebhookEnvelope {
+    /** The declared webhook name. */
+    event: string;
+    /** The extension id the event came from. */
+    source: string;
+    /** When the event happened, as an ISO timestamp. */
+    occurredAt: string;
+    /** The build the event belongs to, when it belongs to one. */
+    build?: string;
+    /** The key Tappify deduplicates on, so a retry is not counted twice. */
+    dedupeKey: string;
+    payload: Record<string, unknown>;
+}
+/** The third argument of `sendEvent`. */
+interface SendEventOptions {
+    /** Which install the event belongs to. */
+    installId: string;
+    extensionId: string;
+    /** The inbound signing secret from the extension's Server page. */
+    secret: string;
+    /** A full url to post to, which replaces `baseUrl` and the built path. */
+    endpoint?: string;
+    /** The Tappify origin to build the path under. Defaults to production. */
+    baseUrl?: string;
+    /** Defaults to a fresh UUID, so give your own to make a retry idempotent. */
+    dedupeKey?: string;
+    build?: string;
+    /** Defaults to now, in ISO form. */
+    occurredAt?: string;
+    /** A `fetch` of your own, for a test or a proxy. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/**
+ * Returns the hex HMAC-SHA-256 of a raw body under a shared secret.
+ *
+ * @remarks
+ * This is the value `sendEvent` sends as `X-Tappify-Signature`, computed over the
+ * exact bytes of the body it posts. Call it directly only when you build the
+ * request yourself, and sign the serialised string you send rather than
+ * re-serialising the object, because a different key order is a different
+ * signature. Uses Web Crypto, so it runs on Node, Cloudflare Workers and Vercel
+ * alike.
+ *
+ * @example
+ * ```ts
+ * import { signWebhook } from '@tappify/extension-sdk/server';
+ *
+ * async function signed(body: string): Promise<Record<string, string>> {
+ *   return { 'x-tappify-signature': await signWebhook('whsec_test', body) };
+ * }
+ * ```
+ */
+declare function signWebhook(secret: string, body: string): Promise<string>;
+/**
+ * Posts one of your declared webhook events to Tappify, signed with the install's
+ * inbound secret.
+ *
+ * @remarks
+ * The name and the payload are narrowed by the `TapWebhookMap` augmentation
+ * `tappify extension types` writes. It builds the envelope, signs the serialised
+ * body and posts it to the install's hook path under `baseUrl`, or to `endpoint`
+ * when you give one. A response Tappify did not accept rejects with a
+ * `TapServerError` whose `code` is always `TAP_WEBHOOK_REJECTED`, carrying the HTTP
+ * status, and with Tappify's own code in the message text rather than in `code`;
+ * the two usual causes are the wrong signing
+ * secret and an event the manifest does not declare. Pass your own `dedupeKey` to
+ * make a retry idempotent, because the default is a fresh UUID.
+ *
+ * @example
+ * ```ts
+ * import { sendEvent } from '@tappify/extension-sdk/server';
+ *
+ * async function reportAnomaly(installId: string, why: string): Promise<void> {
+ *   await sendEvent('anomaly.detected', { why }, {
+ *     installId,
+ *     extensionId: 'starter',
+ *     secret: process.env.TAPPIFY_INBOUND_SECRET ?? '',
+ *     dedupeKey: `anomaly-${installId}-${why}`,
+ *   });
+ * }
+ * ```
+ */
+declare function sendEvent<E extends WebhookName>(name: E, payload: WebhookPayload<E>, options: SendEventOptions): Promise<void>;
+
+/**
+ * The key set `verifyTappifyToken` fetches when no `jwksUrl` or `jwks` is given.
+ *
+ * @remarks
+ * This is production. Point `jwksUrl` at the environment that is calling you when
+ * you run against another one, and pass `jwks` in tests.
+ */
+declare const DEFAULT_JWKS_URL = "https://api.tappify.ai/api/v1/extensions/.well-known/jwks.json";
+/**
+ * Verifies an install token against Tappify's signing keys and returns its
+ * claims.
+ *
+ * @remarks
+ * Checks the RS256 signature, the expiry with 60 seconds of clock tolerance, and
+ * that the audience is `ext:<extensionId>`. Rejects with a `TapError` carrying
+ * `TAP_TOKEN_INVALID` when the signature, the expiry or a required claim is wrong,
+ * and `TAP_TOKEN_AUDIENCE` when the token was issued for another extension. A
+ * remote key set is fetched once per url and cached for the process, so calling
+ * this per request costs nothing after the first. `createTappifyHandler` already
+ * verifies every route but health, so call this only outside the handler, or
+ * where you accept a Tappify token on a route of your own.
+ *
+ * @example
+ * ```ts
+ * import { verifyTappifyToken } from '@tappify/extension-sdk/server';
+ *
+ * async function whoCalled(request: Request): Promise<string> {
+ *   const token = (request.headers.get('authorization') ?? '').replace('Bearer ', '');
+ *   const claims = await verifyTappifyToken(token, { extensionId: 'starter' });
+ *   return claims.installId;
+ * }
+ * ```
+ */
+declare function verifyTappifyToken(token: string, options: VerifyTokenOptions): Promise<TappifyClaims>;
+
+export { type BodyStream, DEFAULT_JWKS_URL, type ExpressLikeRequest, type ExpressLikeResponse, type ExpressMiddleware, type NodeRequestListener, SERVER_ERROR_CODES, type SendEventOptions, type TapServerErrorCode, TappifyClaims, TappifyFetchHandler, VerifyTokenOptions, type WebhookEnvelope, WebhookName, WebhookPayload, sendEvent, signWebhook, toExpress, toNode, verifyTappifyToken };

package/dist/server.d.ts

@@ -0,0 +1,243 @@
+export { c as TapServerError } from './errors-COsBh7kd.js';
+import { ad as WebhookName, ae as WebhookPayload } from './types-DDAGLpov.js';
+export { A as ActionId, k as ActionInput, w as TapCredentialValues, a as TapFilters, c as TapHostEvents, $ as TapSettingsValues, ab as ToolId, ac as ToolInput } from './types-DDAGLpov.js';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { T as TappifyFetchHandler, V as VerifyTokenOptions, a as TappifyClaims } from './handler-CZIlZ5vu.js';
+export { C as ContextBlock, M as MentionItems, b as MetricsInput, c as MetricsResponse, d as MetricsSeries, e as TappifyCallContext, f as TappifyDocuments, g as TappifyHandlerOptions, h as TappifyHealth, i as TappifyInstall, j as TappifyRequest, k as TappifyRouteHandler, W as WorkOperation, l as createTappifyHandler } from './handler-CZIlZ5vu.js';
+import './constants-DJ_KgZpN.js';
+import 'jose';
+
+/**
+ * The part of a Node readable stream the adapters use, so neither adapter has to
+ * name a framework's own request type.
+ */
+interface BodyStream {
+    /** Each chunk of the body, in order. */
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    /** The body is complete. */
+    on(event: 'end', listener: () => void): unknown;
+    /** The stream failed; the adapter rejects with the error. */
+    on(event: 'error', listener: (error: Error) => void): unknown;
+}
+/** The part of an Express request `toExpress` reads. */
+interface ExpressLikeRequest {
+    method: string;
+    /** Preferred over `url`, so a router-mounted path keeps its prefix. */
+    originalUrl?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** A parsed body from `express.json()`, or a raw string. */
+    body?: unknown;
+    /** Used as the scheme of the url handed to the handler. Defaults to `https`. */
+    protocol?: string;
+    /** Present when no parser has consumed the stream, which is then read as-is. */
+    on?: BodyStream['on'];
+}
+/** The part of an Express response `toExpress` writes. */
+interface ExpressLikeResponse {
+    /** Sets the status and returns the response, so the call chains into `send`. */
+    status(code: number): ExpressLikeResponse;
+    /** Called once per header the handler's response carries. */
+    setHeader(name: string, value: string): void;
+    /** Called once, with the handler's response body as text. */
+    send(body: string): void;
+}
+/** What `toExpress` returns: an Express middleware over the three arguments. */
+type ExpressMiddleware = (request: ExpressLikeRequest, response: ExpressLikeResponse, next: (error?: unknown) => void) => void;
+/** What `toNode` returns: a listener for `http.createServer`. */
+type NodeRequestListener = (request: IncomingMessage, response: ServerResponse) => void;
+/**
+ * Wraps the handler as Express middleware, for a server that speaks Express
+ * rather than `fetch`.
+ *
+ * @remarks
+ * It builds the url from `originalUrl` and the `host` header, forwards every
+ * header, and takes the body from `request.body` when a parser has already read
+ * it or from the stream when none has. A request with neither — a parser that
+ * consumed the stream without leaving a body — fails with a `TapServerError`
+ * carrying `TAP_BODY_INVALID` rather than calling your handler against an empty
+ * body, so mount `express.json()` before this middleware or mount this one first.
+ * A `TapServerError` is written as the handler's own JSON error; anything else
+ * goes to `next`, so your own error middleware sees it.
+ *
+ * @example
+ * ```ts
+ * import { createTappifyHandler, toExpress } from '@tappify/extension-sdk/server';
+ *
+ * const middleware = toExpress(
+ *   createTappifyHandler({ extensionId: 'starter', health: () => ({ ok: true }) }),
+ * );
+ * ```
+ */
+declare function toExpress(handler: TappifyFetchHandler): ExpressMiddleware;
+/**
+ * Wraps the handler as a listener for Node's own `http.createServer`, with no
+ * framework in between.
+ *
+ * @remarks
+ * It builds the url from `request.url` and the `host` header over `http`, forwards
+ * every header, and reads the body straight off the stream, so nothing may have
+ * consumed it first. It answers the whole response itself: a `TapServerError`
+ * becomes its own code and status, and anything else becomes 500
+ * `TAP_INTERNAL_ERROR`. Put it behind a TLS-terminating proxy in production; the
+ * scheme it builds is only what the handler sees in `request.url`.
+ *
+ * @example
+ * ```ts
+ * import { createTappifyHandler, toNode } from '@tappify/extension-sdk/server';
+ * import { createServer } from 'node:http';
+ *
+ * const listener = toNode(
+ *   createTappifyHandler({ extensionId: 'starter', health: () => ({ ok: true }) }),
+ * );
+ * const server = createServer(listener);
+ * ```
+ */
+declare function toNode(handler: TappifyFetchHandler): NodeRequestListener;
+
+/**
+ * The codes `createTappifyHandler` answers with itself, keyed by a short name.
+ *
+ * @remarks
+ * Every one of these comes from the SDK, not from your own handlers: a route or
+ * handler that is not there, a token that is missing or does not verify, a missing
+ * event id, a body that is not JSON or is over 1 MB, a webhook Tappify rejected,
+ * and the catch-all for an error a handler let escape. Throw a `TapServerError`
+ * with a code of your own for anything your server decides.
+ */
+declare const SERVER_ERROR_CODES: {
+    readonly ROUTE_UNKNOWN: "TAP_ROUTE_UNKNOWN";
+    readonly HANDLER_MISSING: "TAP_HANDLER_MISSING";
+    readonly INTERNAL_ERROR: "TAP_INTERNAL_ERROR";
+    readonly TOKEN_MISSING: "TAP_TOKEN_MISSING";
+    readonly TOKEN_INVALID: "TAP_TOKEN_INVALID";
+    readonly TOKEN_AUDIENCE: "TAP_TOKEN_AUDIENCE";
+    readonly EVENT_ID_MISSING: "TAP_EVENT_ID_MISSING";
+    readonly BODY_INVALID: "TAP_BODY_INVALID";
+    readonly BODY_TOO_LARGE: "TAP_BODY_TOO_LARGE";
+    readonly WEBHOOK_REJECTED: "TAP_WEBHOOK_REJECTED";
+};
+/** Every code the handler answers with itself, as a union of its own values. */
+type TapServerErrorCode = (typeof SERVER_ERROR_CODES)[keyof typeof SERVER_ERROR_CODES];
+
+/** The body `sendEvent` posts to Tappify, and the body the signature covers. */
+interface WebhookEnvelope {
+    /** The declared webhook name. */
+    event: string;
+    /** The extension id the event came from. */
+    source: string;
+    /** When the event happened, as an ISO timestamp. */
+    occurredAt: string;
+    /** The build the event belongs to, when it belongs to one. */
+    build?: string;
+    /** The key Tappify deduplicates on, so a retry is not counted twice. */
+    dedupeKey: string;
+    payload: Record<string, unknown>;
+}
+/** The third argument of `sendEvent`. */
+interface SendEventOptions {
+    /** Which install the event belongs to. */
+    installId: string;
+    extensionId: string;
+    /** The inbound signing secret from the extension's Server page. */
+    secret: string;
+    /** A full url to post to, which replaces `baseUrl` and the built path. */
+    endpoint?: string;
+    /** The Tappify origin to build the path under. Defaults to production. */
+    baseUrl?: string;
+    /** Defaults to a fresh UUID, so give your own to make a retry idempotent. */
+    dedupeKey?: string;
+    build?: string;
+    /** Defaults to now, in ISO form. */
+    occurredAt?: string;
+    /** A `fetch` of your own, for a test or a proxy. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/**
+ * Returns the hex HMAC-SHA-256 of a raw body under a shared secret.
+ *
+ * @remarks
+ * This is the value `sendEvent` sends as `X-Tappify-Signature`, computed over the
+ * exact bytes of the body it posts. Call it directly only when you build the
+ * request yourself, and sign the serialised string you send rather than
+ * re-serialising the object, because a different key order is a different
+ * signature. Uses Web Crypto, so it runs on Node, Cloudflare Workers and Vercel
+ * alike.
+ *
+ * @example
+ * ```ts
+ * import { signWebhook } from '@tappify/extension-sdk/server';
+ *
+ * async function signed(body: string): Promise<Record<string, string>> {
+ *   return { 'x-tappify-signature': await signWebhook('whsec_test', body) };
+ * }
+ * ```
+ */
+declare function signWebhook(secret: string, body: string): Promise<string>;
+/**
+ * Posts one of your declared webhook events to Tappify, signed with the install's
+ * inbound secret.
+ *
+ * @remarks
+ * The name and the payload are narrowed by the `TapWebhookMap` augmentation
+ * `tappify extension types` writes. It builds the envelope, signs the serialised
+ * body and posts it to the install's hook path under `baseUrl`, or to `endpoint`
+ * when you give one. A response Tappify did not accept rejects with a
+ * `TapServerError` whose `code` is always `TAP_WEBHOOK_REJECTED`, carrying the HTTP
+ * status, and with Tappify's own code in the message text rather than in `code`;
+ * the two usual causes are the wrong signing
+ * secret and an event the manifest does not declare. Pass your own `dedupeKey` to
+ * make a retry idempotent, because the default is a fresh UUID.
+ *
+ * @example
+ * ```ts
+ * import { sendEvent } from '@tappify/extension-sdk/server';
+ *
+ * async function reportAnomaly(installId: string, why: string): Promise<void> {
+ *   await sendEvent('anomaly.detected', { why }, {
+ *     installId,
+ *     extensionId: 'starter',
+ *     secret: process.env.TAPPIFY_INBOUND_SECRET ?? '',
+ *     dedupeKey: `anomaly-${installId}-${why}`,
+ *   });
+ * }
+ * ```
+ */
+declare function sendEvent<E extends WebhookName>(name: E, payload: WebhookPayload<E>, options: SendEventOptions): Promise<void>;
+
+/**
+ * The key set `verifyTappifyToken` fetches when no `jwksUrl` or `jwks` is given.
+ *
+ * @remarks
+ * This is production. Point `jwksUrl` at the environment that is calling you when
+ * you run against another one, and pass `jwks` in tests.
+ */
+declare const DEFAULT_JWKS_URL = "https://api.tappify.ai/api/v1/extensions/.well-known/jwks.json";
+/**
+ * Verifies an install token against Tappify's signing keys and returns its
+ * claims.
+ *
+ * @remarks
+ * Checks the RS256 signature, the expiry with 60 seconds of clock tolerance, and
+ * that the audience is `ext:<extensionId>`. Rejects with a `TapError` carrying
+ * `TAP_TOKEN_INVALID` when the signature, the expiry or a required claim is wrong,
+ * and `TAP_TOKEN_AUDIENCE` when the token was issued for another extension. A
+ * remote key set is fetched once per url and cached for the process, so calling
+ * this per request costs nothing after the first. `createTappifyHandler` already
+ * verifies every route but health, so call this only outside the handler, or
+ * where you accept a Tappify token on a route of your own.
+ *
+ * @example
+ * ```ts
+ * import { verifyTappifyToken } from '@tappify/extension-sdk/server';
+ *
+ * async function whoCalled(request: Request): Promise<string> {
+ *   const token = (request.headers.get('authorization') ?? '').replace('Bearer ', '');
+ *   const claims = await verifyTappifyToken(token, { extensionId: 'starter' });
+ *   return claims.installId;
+ * }
+ * ```
+ */
+declare function verifyTappifyToken(token: string, options: VerifyTokenOptions): Promise<TappifyClaims>;
+
+export { type BodyStream, DEFAULT_JWKS_URL, type ExpressLikeRequest, type ExpressLikeResponse, type ExpressMiddleware, type NodeRequestListener, SERVER_ERROR_CODES, type SendEventOptions, type TapServerErrorCode, TappifyClaims, TappifyFetchHandler, VerifyTokenOptions, type WebhookEnvelope, WebhookName, WebhookPayload, sendEvent, signWebhook, toExpress, toNode, verifyTappifyToken };