@picked/app-kit 0.0.0-stage → 0.0.117-next.2

package/dist/types/frame.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file The handshake between an app's iframe and the dashboard hosting it.
+ *
+ * The frame posts `picked:ready`; the dashboard answers `picked:context` with where the
+ * frame renders and a session token the frame forwards to its own server. The frame can
+ * post `picked:resize` to set its height. Each `picked:ready` gets a context with a new session
+ * token, which `keepConnected` uses to renew the token before it expires.
+ */
+import type { AppSlotLocation } from '@picked/app-protocol';
+/** What the dashboard tells a frame. */
+export interface FrameContext {
+    installationId: string;
+    organizationId: string;
+    organizationSlug: string;
+    projectId: string;
+    /** The slot the frame renders in. */
+    location: AppSlotLocation;
+    /** The installation's pinned app version. */
+    appVersion: number;
+    /** A short-lived token asserting the user and installation; verify it with `readSession`. */
+    sessionToken: string;
+    /** The dashboard's colour scheme. */
+    theme: 'light' | 'dark';
+}
+/** A message the frame posts to the dashboard. */
+export type FrameToHostMessage = {
+    type: 'picked:ready';
+} | {
+    type: 'picked:resize';
+    height: number;
+};
+/** A message the dashboard posts to the frame. */
+export interface HostToFrameMessage {
+    type: 'picked:context';
+    context: FrameContext;
+}
+/**
+ * Connects to the dashboard and resolves with the frame's context. Call once on load. It
+ * works only in a page the Picked dashboard frames: it rejects in a top-level window, and
+ * accepts the context only from the frame's parent window on the dashboard's origin.
+ *
+ * @param {object} [options] - Connection options.
+ * @param {string} [options.dashboardOrigin] - The dashboard origin to accept and post to; the referrer's when absent.
+ * @returns {Promise<FrameContext>} Where the frame renders and who is looking.
+ * @example const context = await connect()
+ */
+export declare function connect(options?: {
+    dashboardOrigin?: string;
+}): Promise<FrameContext>;
+/** A connection to the dashboard that renews its session token before the token expires. */
+export interface FrameConnection {
+    /**
+     * Returns the newest context the dashboard sent. Read it for each request and each
+     * `authorizeInPopup`, so they carry a session token that has not expired.
+     */
+    context: () => FrameContext;
+    /** Stops renewing the session token. */
+    stop: () => void;
+}
+/**
+ * Connects to the dashboard as `connect` does, then asks the dashboard for a new context two
+ * minutes before each session token expires and at most four minutes after the last one. It
+ * checks the clock every 15 seconds and when the frame regains focus or visibility, and asks
+ * again 15 seconds after a renewal the dashboard leaves unanswered for 10 seconds. Call once
+ * on load, in place of `connect`.
+ *
+ * @param {object} [options] - Connection options.
+ * @param {string} [options.dashboardOrigin] - The dashboard origin to accept and post to; the referrer's when absent.
+ * @returns {Promise<FrameConnection>} The connection, once the dashboard sends the first context.
+ * @example const connection = await keepConnected()
+ */
+export declare function keepConnected(options?: {
+    dashboardOrigin?: string;
+}): Promise<FrameConnection>;
+/**
+ * Sets the frame's height in the dashboard.
+ *
+ * @param {number} height - The height in pixels.
+ * @returns {void}
+ * @example resize(document.body.scrollHeight)
+ */
+export declare function resize(height: number): void;
+/**
+ * Keeps the frame's height matched to its content.
+ *
+ * @returns {() => void} Stops observing.
+ * @example const stop = autoResize()
+ */
+export declare function autoResize(): () => void;
+/** How an authorization the frame opened in a popup ended. */
+export interface AuthorizationResult {
+    ok: boolean;
+    message: string;
+}
+/** What the frame starts an authorization with. */
+export interface AuthorizationRequest {
+    /** The session token from the frame's context, which the popup's start request carries. */
+    sessionToken: string;
+    /** What the app's `/oauth/start` hands its `authorize` as `params`, such as a data centre. */
+    params?: unknown;
+    /**
+     * Reads whether the app now holds the connection, answering the message to show when it
+     * does and null when it does not. Once the popup reads as closed without reporting back,
+     * the frame asks it every second for thirty seconds and settles on the first message.
+     */
+    connected?: () => Promise<string | null>;
+}
+/**
+ * Runs an OAuth authorization in a popup. Call it from a click handler: the popup opens at
+ * once on the app's `/oauth/start`, which asks for the session, and this frame answers that
+ * popup alone with the session token and params. It accepts messages only from that popup, on
+ * the app's own origin. The start binds the authorization to the browser with a cookie and
+ * goes on to the provider. The promise settles when the app's
+ * callback page reports back, or once the popup reads as closed and this frame has focus. A
+ * popup a provider's `Cross-Origin-Opener-Policy` separates from this frame reads as closed
+ * while the user may still be connecting in it, so the frame waits for the user to come back,
+ * then asks `connected` until the app holds the connection the popup saves.
+ *
+ * @param {AuthorizationRequest} request - The session token and the start's params.
+ * @returns {Promise<AuthorizationResult>} How the authorization ended.
+ * @example button.onclick = async () => show(await authorizeInPopup({ sessionToken: context.sessionToken }))
+ */
+export declare function authorizeInPopup(request: AuthorizationRequest): Promise<AuthorizationResult>;
+//# sourceMappingURL=frame.d.ts.map

package/dist/types/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,QAAQ,EAAE,eAAe,CAAA;IACzB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;CACxB;AAED,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAC5B;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtE,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;CACtB;AAqFD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAKzF;AAsED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,YAAY,CAAA;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GACzC,OAAO,CAAC,eAAe,CAAC,CAoC1B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,IAAI,CAKvC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAA;IACpB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACzC;AAoCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6D5F"}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file `@picked/app-kit`: the app manifest and the protocol Picked speaks to apps, re-exported
+ * from `@picked/app-protocol`.
+ *
+ * `@picked/app-kit/server` builds an app's endpoint, `@picked/app-kit/node` serves it, and
+ * `@picked/app-kit/frame` runs inside a dashboard slot's iframe.
+ */
+export * from '@picked/app-protocol';
+export type { FrameContext, FrameToHostMessage, HostToFrameMessage } from './frame';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,sBAAsB,CAAA;AACpC,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA"}

package/dist/types/link.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file The dashboard link that opens the installation a label names, for an app to send a
+ * person from its own site back to the right project in Picked.
+ */
+/**
+ * Tells whether a value has the shape of an app ID.
+ *
+ * @param {string} value - The value.
+ * @returns {boolean} Whether it is `app_` and lowercase letters and digits.
+ * @example isAppId('app_k3v9x2m1q8zt') // true
+ */
+export declare function isAppId(value: string): boolean;
+/** What a link to an installation names. */
+export interface InstallationLink {
+    /** The dashboard's origin, such as `https://app.picked.app`. A path on it is ignored. */
+    dashboardOrigin: string;
+    /**
+     * The app's ID on that dashboard's Picked, such as `app_k3v9x2m1q8zt`, which
+     * `picked app deploy` prints. Each Picked environment gives the app its own ID.
+     */
+    appId: string;
+    /** The namespace of a plain label the app keeps on the installation. */
+    namespace: string;
+    /** The label's key within its namespace. */
+    key: string;
+    /** The value the installation's label holds. */
+    value: string;
+}
+/**
+ * Builds the dashboard URL that opens the installation of an app holding a plain label with a
+ * value: `/apps/<app ID>/open?label=<namespace>.<key>&value=<value>`. The dashboard opens the
+ * one installation the signed-in person can see, or offers a choice of several. A secret label
+ * never matches.
+ *
+ * @param {InstallationLink} link - The dashboard, app, label and value.
+ * @returns {string} The URL.
+ * @throws {TypeError} When the app ID, namespace or key is not one Picked holds, or the origin is not a URL.
+ * @example installationLinkUrl({ dashboardOrigin: 'https://app.picked.app', appId: 'app_k3v9x2m1q8zt', namespace: 'vercel', key: 'configuration-id', value: 'icfg_123' })
+ */
+export declare function installationLinkUrl(link: InstallationLink): string;
+//# sourceMappingURL=link.d.ts.map

package/dist/types/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/link.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;AAKD,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAUlE"}

package/dist/types/node.d.ts

@@ -0,0 +1,19 @@
+import type { Server } from 'node:http';
+/**
+ * Serves a handler on a port, logging each request's method, path and status.
+ *
+ * @param {(request: Request) => Promise<Response>} handler - The handler.
+ * @param {number} port - The port.
+ * @returns {Server} The listening server.
+ * @example serve(createAppHandler(options), 4100)
+ */
+export declare function serve(handler: (request: Request) => Promise<Response>, port: number): Server;
+/**
+ * Answers with the browser build of `@picked/app-kit/frame`, for an app's pages to import as
+ * `/app-kit/frame.js`.
+ *
+ * @returns {Promise<Response>} The script.
+ * @example if (path === '/app-kit/frame.js') return frameScript()
+ */
+export declare function frameScript(): Promise<Response>;
+//# sourceMappingURL=node.d.ts.map

package/dist/types/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAA;AA0DxE;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgB5F;AAGD;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAGrD"}

package/dist/types/oauth.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @file OAuth authorization-code helpers for apps that connect an installation to a third
+ * party. The popup starts at the app's `/oauth/start`, which takes the dashboard session from
+ * the frame that opened it, sets a cookie holding a nonce, and sends the browser to the
+ * provider with a sealed `state` carrying the installation and that nonce. The provider's
+ * callback completes only in the browser whose cookie holds the state's nonce, and its page
+ * tells the frame how it went.
+ */
+import { type PublicKeySet, type SessionClaims } from '@picked/app-protocol';
+/** The message the callback page posts to the frame that opened it. */
+export declare const OAUTH_RESULT_MESSAGE = "picked-app:oauth-result";
+/** The message the start page posts to its opener once it can take the session. */
+export declare const OAUTH_START_READY_MESSAGE = "picked-app:oauth-start-ready";
+/** The message the opener answers the start page with: the session token and the start's params. */
+export declare const OAUTH_START_MESSAGE = "picked-app:oauth-start";
+/** The path an app serves the popup's start page (`GET`) and its start request (`POST`) at. */
+export declare const OAUTH_START_PATH = "/oauth/start";
+/** What the `state` parameter carries through the provider. */
+export interface OAuthState {
+    /** The installation being connected. */
+    installationId: string;
+    /** The Picked API the installation calls back. */
+    apiUrl: string;
+    /** Which connection this is, for an app with more than one provider or data centre. */
+    connection: string;
+    /**
+     * The session token of the dashboard user who started the connection, with which the
+     * callback mints a token to save it.
+     */
+    sessionToken: string;
+    /** Expiry, in unix seconds. */
+    exp: number;
+    /** The value of the cookie the start set in the browser that began the authorization. */
+    nonce: string;
+}
+/**
+ * Renders the page a provider's callback answers with. It posts the result to the frame that
+ * opened the popup, on the app's own origin, and closes. A popup whose opener is gone, as a
+ * provider's `Cross-Origin-Opener-Policy` can leave it, stays open showing the result.
+ *
+ * @param {object} result - How the authorization went.
+ * @param {boolean} result.ok - Whether the connection was saved.
+ * @param {string} result.message - What to tell the user.
+ * @returns {string} The page's HTML.
+ * @example oauthCallbackPage({ ok: true, message: 'Connected' })
+ */
+export declare function oauthCallbackPage(result: {
+    ok: boolean;
+    message: string;
+}): string;
+/**
+ * Renders the page the popup opens at. It tells the frame that opened it that it is ready,
+ * takes the session token and params that frame answers with, from that frame alone, and
+ * posts them to its own path. That answer sets the binding cookie and names the provider's
+ * URL, which the page goes to; a refusal goes to the frame as the result.
+ *
+ * @returns {string} The page's HTML.
+ * @example oauthStartPage()
+ */
+export declare function oauthStartPage(): string;
+/** An authorization the popup asked to start. */
+export interface AuthorizationStart {
+    /** The verified session of the dashboard user starting it. */
+    session: SessionClaims;
+    /** The raw session token, which an installation client passes on as `sessionToken`. */
+    sessionToken: string;
+    /** What the app's page passed `authorizeInPopup` as `params`, or null. */
+    params: unknown;
+    /**
+     * Seals the `state` for a connection of the session's installation, carrying the session
+     * token and the nonce of the cookie this start sets.
+     */
+    state: (connection: string) => Promise<string>;
+}
+/** What `startAuthorization` is given. */
+export interface StartAuthorizationOptions {
+    /** The app's private key, from which the state's key derives. */
+    privateKey: string;
+    /** Picked's public keys, which sign session tokens. */
+    pickedKeys: PublicKeySet;
+    /**
+     * Builds the provider's authorization URL with a `state` from `start.state`, or answers a
+     * refusal, which goes back to the frame and sets no cookie.
+     */
+    authorize: (start: AuthorizationStart) => Promise<string | Response>;
+}
+/**
+ * Answers the app's `/oauth/start`. `GET` serves the popup's page. `POST`, which that page
+ * sends with the session token as `Authorization: Bearer <token>` and the params as its JSON
+ * body, verifies the session, sets the binding cookie to a fresh nonce, and answers
+ * `{ url }`: the provider's URL `authorize` builds.
+ *
+ * @param {Request} request - The request to `/oauth/start`.
+ * @param {StartAuthorizationOptions} options - The app's keys and its provider's URL.
+ * @returns {Promise<Response>} The page, the provider's URL, or a refusal.
+ * @example if (pathname === OAUTH_START_PATH) return startAuthorization(request, { privateKey, pickedKeys, authorize })
+ */
+export declare function startAuthorization(request: Request, options: StartAuthorizationOptions): Promise<Response>;
+/** A provider's callback in the browser that started the authorization. */
+export interface OAuthCallback {
+    /** The state the start sealed. */
+    state: OAuthState;
+    /** The callback URL, carrying the provider's `code` or `error`. */
+    url: URL;
+}
+/** What `finishAuthorization` is given. */
+export interface FinishAuthorizationOptions {
+    /** The app's private key, from which the state's key derives. */
+    privateKey: string;
+    /** Exchanges the code and saves the connection, answering what the popup reports. */
+    complete: (callback: OAuthCallback) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Answers a provider's callback. It refuses a forged, changed or expired state, and a state
+ * whose nonce differs from the binding cookie the request carries, leaving that cookie in
+ * place. Otherwise it clears the cookie, so the callback completes once, and answers the page
+ * reporting what `complete` returns.
+ *
+ * @param {Request} request - The callback request.
+ * @param {FinishAuthorizationOptions} options - The app's key and its completion.
+ * @returns {Promise<Response>} The callback page.
+ * @example if (pathname === '/oauth/callback') return finishAuthorization(request, { privateKey, complete })
+ */
+export declare function finishAuthorization(request: Request, options: FinishAuthorizationOptions): Promise<Response>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/types/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAA;AAK7B,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,4BAA4B,CAAA;AAE7D,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,iCAAiC,CAAA;AAEvE,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,2BAA2B,CAAA;AAE3D,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;CACd;AAwHD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAkBlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,MAAM,CA0CvC;AA4GD,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,OAAO,EAAE,aAAa,CAAA;IACtB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAA;IACf;;;OAGG;IACH,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC/C;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,UAAU,EAAE,YAAY,CAAA;IACxB;;;OAGG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAA;CACrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,QAAQ,CAAC,CAiCnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,UAAU,CAAA;IACjB,mEAAmE;IACnE,GAAG,EAAE,GAAG,CAAA;CACT;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,QAAQ,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,QAAQ,CAAC,CAqBnB"}

package/dist/types/server.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @file The app server: a fetch-style handler that checks Picked's signature and routes
+ * lifecycle events, app events, tool calls and MCP requests, plus the responses its pages
+ * and APIs answer with.
+ */
+import { type AppEvent, type AppManifest, type InstallationCreatedEvent, type InstallationDeletedEvent, type InstallationRef, type InstallationUpgradedEvent, type PublicKeySet, type SessionClaims, type ToolCall } from '@picked/app-protocol';
+export * from '@picked/app-protocol';
+export * from './client';
+export * from './link';
+/** A tool's body: given the call, returns what the manifest's `output` declares. */
+export type ToolHandler = (call: ToolCall) => Promise<Record<string, unknown>>;
+/** What an app server handles. */
+export interface AppHandlerOptions {
+    /** Picked's public keys, which every request Picked sends must be signed by. */
+    pickedKeys: PublicKeySet;
+    /** The path the manifest's `endpoint` points at, such as `/picked`. Empty by default. */
+    basePath?: string;
+    /** Called when the app is installed on a project. */
+    onInstall?: (event: InstallationCreatedEvent) => Promise<void> | void;
+    /** Called when an installation moves to another version. */
+    onUpgrade?: (event: InstallationUpgradedEvent) => Promise<void> | void;
+    /** Called when the app is removed from a project. */
+    onUninstall?: (event: InstallationDeletedEvent) => Promise<void> | void;
+    /** Called with each event the manifest's `events` subscribes to. */
+    onEvent?: (event: AppEvent) => Promise<void> | void;
+    /** The tool bodies, by the names the manifest declares. */
+    tools?: Record<string, ToolHandler>;
+    /** The MCP server at the manifest's `mcp.url`, and the handler for the signed requests to it. */
+    mcp?: {
+        /** The pathname of the manifest's `mcp.url`, such as `/mcp`, matched against the full path. */
+        path: string;
+        handle: (request: Request, installation: InstallationRef) => Promise<Response>;
+    };
+    /** The app's manifest, which the handler serves at `GET /manifest.json`. */
+    manifest?: AppManifest;
+    /** Everything else the app serves, such as its frame pages. */
+    fallback?: (request: Request) => Promise<Response> | Response;
+}
+/**
+ * Answers JSON.
+ *
+ * @param {unknown} body - The body.
+ * @param {number} [status] - The status; 200 by default.
+ * @returns {Response} The response.
+ * @example json({ ok: true })
+ */
+export declare function json(body: unknown, status?: number): Response;
+/**
+ * Answers an HTML page the dashboard may frame and no other site may.
+ *
+ * @param {string} html - The page.
+ * @param {object} options - Who may frame it.
+ * @param {string[]} options.frameAncestors - The dashboard origins, such as `https://app.picked.app`.
+ * @returns {Response} The response.
+ * @example page(settingsPage(), { frameAncestors: ['https://app.picked.app'] })
+ */
+export declare function page(html: string, options: {
+    frameAncestors: string[];
+}): Response;
+/**
+ * Builds the handler for an app's endpoint.
+ *
+ * @param {AppHandlerOptions} options - What the app handles.
+ * @returns {(request: Request) => Promise<Response>} A fetch-style handler.
+ * @example serve(createAppHandler({ pickedKeys: environment.pickedKeys, tools: { ping: async () => ({ ok: true }) } }))
+ */
+export declare function createAppHandler(options: AppHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Reads the raw session token a frame sends as `Authorization: Bearer <token>`, which an
+ * installation client passes on as `sessionToken` to mint a token for that user's request.
+ *
+ * @param {Request} request - The frame's request to the app's own server.
+ * @returns {string | null} The token, or null when the request carries none.
+ * @example createInstallationClient({ ...options, sessionToken: sessionTokenOf(request) ?? undefined })
+ */
+export declare function sessionTokenOf(request: Request): string | null;
+/**
+ * Reads the session token a frame sends as `Authorization: Bearer <token>`.
+ *
+ * @param {Request} request - The frame's request to the app's own server.
+ * @param {PublicKeySet} pickedKeys - Picked's public keys, which sign session tokens.
+ * @returns {Promise<SessionClaims | null>} Who is asking, or null without a valid token.
+ * @example const session = await readSession(request, environment.pickedKeys)
+ */
+export declare function readSession(request: Request, pickedKeys: PublicKeySet): Promise<SessionClaims | null>;
+/** What every app server reads from its environment. */
+export interface AppEnvironment {
+    /** `PICKED_APP_PRIVATE_KEY`: the app's Ed25519 private key, as the base64 of its PKCS#8 DER or a PKCS#8 PEM. */
+    privateKey: string;
+    /** `PICKED_API_URL`: the Picked API the app trusts, whose public keys verify Picked's requests. */
+    pickedUrl: string;
+    /** Picked's public keys, read from `pickedUrl`. */
+    pickedKeys: PublicKeySet;
+    /** `APP_PUBLIC_URL`: the origin the app is served at, which its manifest's endpoint names. */
+    publicUrl: string;
+    /**
+     * The dashboard origins the environment names: `PICKED_DASHBOARD_ORIGINS`, or `DASHBOARD_PORT`
+     * on localhost; empty when it names none.
+     */
+    frameAncestors: string[];
+    /**
+     * The dashboard origins that may frame the app's pages, the dashboard's own first, which an
+     * app links people to as `installationLinkUrl`'s `dashboardOrigin`: `frameAncestors`, or the
+     * ones Picked's app config at `pickedUrl` lists when the environment names none.
+     */
+    dashboardOrigins: () => Promise<string[]>;
+    /**
+     * `PICKED_APP_ID`: the app's ID on the Picked it trusts, which `picked app deploy` prints, or
+     * null when it is unset or not an app ID.
+     */
+    appId: string | null;
+}
+/**
+ * The dashboard origins Picked's app config lists. It fetches the config on first use, on every
+ * use until a fetch succeeds, and again on a use once `refreshAfterMs` has passed since the last
+ * success. A fetch that takes longer than `timeoutMs` is abandoned. It keeps the origins it last
+ * read when a fetch fails, and holds none before any fetch succeeds.
+ *
+ * @param {object} options - Where the config lives.
+ * @param {string} options.url - The config's URL.
+ * @param {typeof fetch} [options.fetch] - The fetch to read it with.
+ * @param {number} [options.refreshAfterMs] - The least time between fetches; five minutes by default.
+ * @param {number} [options.timeoutMs] - The longest a fetch may take; five seconds by default.
+ * @returns {() => Promise<string[]>} Reads the origins.
+ * @example remoteDashboardOrigins({ url: 'https://api.picked.app/.well-known/picked-app-config.json' })
+ */
+export declare function remoteDashboardOrigins(options: {
+    url: string;
+    fetch?: typeof fetch;
+    refreshAfterMs?: number;
+    timeoutMs?: number;
+}): () => Promise<string[]>;
+/**
+ * Reads an app server's environment. An origin the environment leaves unset comes from
+ * Vercel when the app runs there: Picked's API from the related project `picked-api`, and the
+ * public URL from `VERCEL_PROJECT_PRODUCTION_URL` in production and `VERCEL_BRANCH_URL`
+ * elsewhere, so a preview targets the API deployed from its own branch. Locally, Picked's API
+ * defaults to `API_PORT` on localhost, the public URL to the app's port and the frame
+ * ancestors to the dashboard's port. The dashboard origins are the frame ancestors, or, when the
+ * environment names none, the ones in the app config Picked's API publishes: the dashboard's
+ * own origin first, then every tenant host.
+ *
+ * @param {Record<string, string | undefined>} env - The environment.
+ * @param {string} port - The port the app listens on locally.
+ * @param {object} [options] - How Picked's documents are read.
+ * @param {typeof fetch} [options.fetch] - The fetch Picked's keys and app config are read with.
+ * @param {number} [options.refreshAfterMs] - The least time between reads of Picked's app config.
+ * @param {number} [options.timeoutMs] - The longest a read of Picked's app config may take.
+ * @returns {AppEnvironment} The environment.
+ * @throws {Error} When `PICKED_APP_PRIVATE_KEY` or `PICKED_API_URL` is unset.
+ * @example readAppEnvironment(process.env, process.env.APP_PORT ?? '4101')
+ */
+export declare function readAppEnvironment(env: Record<string, string | undefined>, port: string, options?: {
+    fetch?: typeof fetch;
+    refreshAfterMs?: number;
+    timeoutMs?: number;
+}): AppEnvironment;
+/**
+ * Serves a handler behind a Vercel rewrite of every path to `/api?__path=/:path*`, restoring
+ * the path the request was sent to.
+ *
+ * @param {(request: Request) => Promise<Response>} handler - The app's handler.
+ * @returns {(request: Request) => Promise<Response>} The handler for `api/index.ts`.
+ * @example export default { fetch: withRewrittenPath(handler) }
+ */
+export declare function withRewrittenPath(handler: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+//# sourceMappingURL=server.d.ts.map

package/dist/types/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types/testing.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Test doubles for app servers: a fake Picked API that answers the GraphQL operations the
+ * installation client sends, mints tokens for app assertions signed with the app's key (for an
+ * installation without offline access, only alongside a session token it signed), keeps
+ * installation labels and publishes Picked's public keys; and helpers that build the requests
+ * Picked and the dashboard send an app, signed with the fake's Picked key.
+ */
+import { type InstallationRef, type PublicKeySet, type ToolCall } from '@picked/app-protocol';
+import type { AppLabel } from './client';
+/** A GraphQL operation the fake received. */
+export interface ReceivedOperation {
+    operationName: string;
+    variables: Record<string, unknown>;
+}
+/** A fake Picked API for one app. */
+export interface FakePicked {
+    /** The fake's API origin. */
+    apiUrl: string;
+    /** The fetch to hand the app as its Picked sender. */
+    fetch: typeof fetch;
+    /** Picked's public keys, as an app verifies Picked's requests with them. */
+    pickedKeys: PublicKeySet;
+    /** Each installation's labels, by installation id, then by `<namespace>.<key>`. */
+    labels: Map<string, Map<string, AppLabel>>;
+    /** Every GraphQL operation received, in order. */
+    received: ReceivedOperation[];
+    /** Mints a token for an installation, as Picked sends one with each request. */
+    tokenFor: (installationId: string) => Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Names an installation as a request from Picked does: on the fake's API, with a fresh token,
+     * in organisation `org` and project `proj_1` unless the overrides say otherwise.
+     */
+    installationRef: (installationId: string, overrides?: Partial<Pick<InstallationRef, 'organizationId' | 'projectId'>>) => Promise<InstallationRef>;
+    /** Builds a request Picked sends the app, signed with Picked's key. */
+    signedRequest: (url: string, payload: unknown) => Promise<Request>;
+    /** Builds an MCP request Picked forwards to the app, signed with Picked's key. */
+    mcpRequest: (url: string, ref: InstallationRef, payload: unknown) => Promise<Request>;
+    /** Builds a request from a dashboard user viewing an installation's frame. */
+    sessionRequest: (params: {
+        ref: InstallationRef;
+        url: string;
+        method?: string;
+        body?: unknown;
+    }) => Promise<Request>;
+}
+/**
+ * Builds a fake Picked API that trusts one app's key.
+ *
+ * @param {object} options - The app.
+ * @param {string} options.appPrivateKey - The app's private key, whose public half the fake trusts.
+ * @param {string} [options.apiUrl] - The fake's API origin.
+ * @param {boolean} [options.offlineAccess] - Whether every installation holds offline access.
+ * @returns {Promise<FakePicked>} The fake.
+ * @example const picked = await createFakePicked({ appPrivateKey: privateKey })
+ */
+export declare function createFakePicked(options: {
+    appPrivateKey: string;
+    apiUrl?: string;
+    offlineAccess?: boolean;
+}): Promise<FakePicked>;
+/**
+ * Builds a workflow tool call to an installation.
+ *
+ * @param {InstallationRef} ref - The installation.
+ * @param {string} tool - The tool.
+ * @param {Record<string, unknown>} args - Its arguments.
+ * @param {boolean} [test] - Whether the call belongs to a test run.
+ * @returns {ToolCall} The call.
+ * @example toolCall(ref, 'create_lead', { lastName: 'Lovelace' })
+ */
+export declare function toolCall(ref: InstallationRef, tool: string, args: Record<string, unknown>, test?: boolean): ToolCall;
+/**
+ * Reads the cookie an OAuth start set, as the `cookie` header the browser sends with the
+ * provider's callback.
+ *
+ * @param {Response} response - The answer to `POST /oauth/start`.
+ * @returns {string} The `<name>=<value>` pair, or an empty string when it set none.
+ * @example new Request(callbackUrl, { headers: { cookie: oauthCookie(started) } })
+ */
+export declare function oauthCookie(response: Response): string;
+//# sourceMappingURL=testing.d.ts.map

package/dist/types/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAaL,KAAK,eAAe,EACpB,KAAK,YAAY,EAEjB,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAA+B,MAAM,UAAU,CAAA;AAErE,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,4EAA4E;IAC5E,UAAU,EAAE,YAAY,CAAA;IACxB,mFAAmF;IACnF,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC1C,kDAAkD;IAClD,QAAQ,EAAE,iBAAiB,EAAE,CAAA;IAC7B,gFAAgF;IAChF,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnF;;;OAGG;IACH,eAAe,EAAE,CACf,cAAc,EAAE,MAAM,EACtB,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,gBAAgB,GAAG,WAAW,CAAC,CAAC,KACvE,OAAO,CAAC,eAAe,CAAC,CAAA;IAC7B,uEAAuE;IACvE,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAClE,kFAAkF;IAClF,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACrF,8EAA8E;IAC9E,cAAc,EAAE,CAAC,MAAM,EAAE;QACvB,GAAG,EAAE,eAAe,CAAA;QACpB,GAAG,EAAE,MAAM,CAAA;QACX,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,IAAI,CAAC,EAAE,OAAO,CAAA;KACf,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACvB;AAuKD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgItB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,UAAQ,GACX,QAAQ,CASV;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEtD"}