@foir/sdk 0.7.0 → 0.8.0

package/dist/graphql/cdn-route.d.ts

@@ -1,5 +1,17 @@
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type FoirEnv } from '../transport/foir-http';
+/**
+ * The shared read lane, for `@foir/sdk/client`.
+ *
+ * The mechanics — the URL, the hash, the handshake codes — moved to
+ * `../transport/persisted-query`, which has no `graphql` import, so
+ * `@foir/sdk/data` can build the same requests without dragging the parser into
+ * a storefront bundle. They are re-exported unchanged; this module's public
+ * surface is exactly what it always was. What stayed here is the part that
+ * needs a parsed document: `print`, and the eligibility rule that reads the
+ * printed text.
+ */
+export { buildCdnUrl, documentHash, hasFoirErrorCode, NOT_SHAREABLE, PERSISTED_QUERY_NOT_FOUND, persistedQueryExtension, } from '../transport/persisted-query';
 /**
  * Whether this read can be served by the shared endpoint.
  *
@@ -10,33 +22,5 @@ import { type FoirEnv } from '../transport/foir-http';
  * saved.
  */
 export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string): boolean;
-/**
- * Build the shared-endpoint URL for a read.
- *
- * The credential goes in the URL deliberately: a shared cache keys on the URL
- * alone, so a key that rode only in a header would let two callers with
- * different reach collide on one entry and be served each other's body.
- */
-export declare function buildCdnUrl(endpoint: string, apiKey: string, hash: string, variables?: unknown): string;
-/** The APQ handshake object, in Apollo's shape because every client uses it. */
-export declare function persistedQueryExtension(hash: string): {
-    persistedQuery: {
-        version: number;
-        sha256Hash: string;
-    };
-};
-/**
- * SHA-256 of the document text, hex encoded — the identity a persisted query is
- * stored and retrieved under.
- *
- * Web Crypto rather than a bundled implementation: it is present in every
- * runtime this SDK targets (workers, edge, Node 18+) and adds nothing to the
- * caller's bundle.
- */
-export declare function documentHash(documentText: string): Promise<string>;
-/** The code the server answers with when it has never seen this hash. */
-export declare const PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
-/** The code the shared endpoint refuses with, so a caller knows to retry. */
-export declare const NOT_SHAREABLE = "NOT_SHAREABLE";
 /** Print a document once, so eligibility and the URL agree on the same text. */
 export declare function printDocument<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>): string;

package/dist/media/index.d.ts

@@ -1,8 +1,10 @@
 /**
- * `@foir/sdk/media` — progressive media components + Foir media adapters.
+ * `@foir/sdk/media` — progressive media components, Foir media adapters, and
+ * screen capture.
  *
  * `react` is a peer dependency; `hls.js` and `blurhash` are optional peers
- * loaded lazily (video/blurhash gracefully no-op when absent).
+ * loaded lazily (video/blurhash gracefully no-op when absent). The capture
+ * helpers are browser-only and pull in neither.
  */
 export { ProgressiveMedia } from './ProgressiveMedia';
 export type { ProgressiveMediaProps } from './ProgressiveMedia';
@@ -12,3 +14,5 @@ export { useProgressiveLoad } from './useProgressiveLoad';
 export type { LoadStage, UseProgressiveLoadOptions } from './useProgressiveLoad';
 export { toProgressiveImage, toProgressiveVideo, effectiveImageDimensions, cropAspectRatio, DEFAULT_VARIANT_TIERS, } from './media';
 export type { VariantTier, VariantSet, VariantTierKey, ProgressiveImageSource, ProgressiveVideoSource, FoirImageInput, FoirVideoInput, } from './media';
+export { captureFoirScreen, isFoirScreenCaptureSupported } from './screen-capture';
+export type { FoirScreenCapture, FoirScreenCaptureOptions } from './screen-capture';

package/dist/media/media.d.ts

@@ -72,7 +72,7 @@ export interface ProgressiveVideoSource {
     duration?: number;
 }
 /**
- * Foir GraphQL `ImageValue`-like input — the shape a consumer's codegen
+ * Foir GraphQL `Image`-like input — the shape a consumer's codegen
  * produces for an image field (intrinsic dims + per-format variant sets +
  * crop as opaque JSON). Structurally compatible with the generated type.
  */
@@ -89,7 +89,7 @@ export interface FoirImageInput {
         [key: string]: unknown;
     } | null;
 }
-/** Foir GraphQL `VideoValue`-like input. */
+/** Foir GraphQL `Video`-like input. */
 export interface FoirVideoInput {
     url?: string | null;
     width?: number | null;

package/dist/media/screen-capture.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Screen capture — a picture of what the reader was looking at.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it lives in the SDK
+ * ---------------------------------------------------------------------------
+ *
+ * Two surfaces need the same picture: the console's own bug report, and the
+ * feedback widget a customer's visitors use (`@foir/sdk/react`). One of those
+ * ships to npm and the other does not, so the shared half has to sit in the
+ * published package — a copy in each would be two answers to "how big is a
+ * screenshot", free to drift, and the drift would only show up as an upload the
+ * storage quota measures differently from the preview.
+ *
+ * ---------------------------------------------------------------------------
+ * The browser's picker IS the consent gate
+ * ---------------------------------------------------------------------------
+ *
+ * `getDisplayMedia` cannot be called without a user gesture and cannot resolve
+ * without the person choosing a surface in the browser's own dialog. So there is
+ * nothing here that asks for permission separately, and nothing that could
+ * capture without the reader having picked what to hand over. Call this from a
+ * click handler and from nowhere else.
+ *
+ * The stream is stopped before this function returns, on every path — a capture
+ * that left the tracks live would leave the browser's "sharing your screen"
+ * indicator on after a single still frame.
+ */
+/** How the still is encoded. Both have defaults; neither is read from anywhere else. */
+export interface FoirScreenCaptureOptions {
+    /**
+     * Longest horizontal edge of the still, in pixels. Wider captures are scaled
+     * down proportionally; narrower ones are left alone rather than upscaled.
+     *
+     * Default 1600, which is a readable full-page shot of a 4K display and lands
+     * around 200-400kB as JPEG. It is a bound on the bytes a reader uploads over
+     * their own connection, not a quality target.
+     */
+    maxWidth?: number;
+    /** JPEG quality, 0 to 1. Default 0.7. */
+    quality?: number;
+}
+/** One captured still. */
+export interface FoirScreenCapture {
+    /** The bytes, for upload. `size` on it is what the storage quota measures. */
+    blob: Blob;
+    /**
+     * The same bytes as a `data:` URL, for an `<img src>` preview.
+     *
+     * Both, rather than one plus a converter, because the two callers need
+     * different halves and neither should re-encode: an object URL has a lifetime
+     * to manage and a second `toDataURL` would be a second encode of one frame.
+     */
+    dataUrl: string;
+    /** The still's own dimensions, after any downscale. */
+    width: number;
+    height: number;
+    mimeType: string;
+}
+/**
+ * Whether this browser can capture at all.
+ *
+ * Ask before rendering a capture button. `getDisplayMedia` is absent on every
+ * iOS browser and on any page served over plain HTTP, and a button that can only
+ * produce an error message is worse than no button.
+ */
+export declare function isFoirScreenCaptureSupported(): boolean;
+/**
+ * Capture one still of a surface the reader picks.
+ *
+ * Returns `null` when they dismissed the picker — that is a decision, not a
+ * failure, and a caller that treated it as one would put an error in front of
+ * somebody who just changed their mind. Everything else throws.
+ *
+ * The one ambiguity worth stating: a page embedded in an iframe without
+ * `allow="display-capture"` is refused with the SAME `NotAllowedError` the
+ * dismissal produces, so it lands here as `null` too. The browser gives no way
+ * to tell the two apart, and guessing wrong in the other direction would mean an
+ * error toast on every cancel.
+ */
+export declare function captureFoirScreen(options?: FoirScreenCaptureOptions): Promise<FoirScreenCapture | null>;

package/dist/media.js

@@ -392,12 +392,109 @@ function ProgressiveMedia({
     }
   );
 }
+
+// src/media/screen-capture.ts
+var DEFAULT_MAX_WIDTH = 1600;
+var DEFAULT_QUALITY = 0.7;
+var CAPTURE_MIME_TYPE = "image/jpeg";
+function isFoirScreenCaptureSupported() {
+  return typeof navigator !== "undefined" && typeof navigator.mediaDevices?.getDisplayMedia === "function";
+}
+async function captureFoirScreen(options = {}) {
+  if (!isFoirScreenCaptureSupported()) {
+    throw new Error(
+      "[foir] this browser cannot capture the screen: navigator.mediaDevices.getDisplayMedia is unavailable. It needs a secure context (https, or localhost) and is absent on iOS. Call isFoirScreenCaptureSupported() before offering capture."
+    );
+  }
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const quality = options.quality ?? DEFAULT_QUALITY;
+  let stream;
+  try {
+    stream = await navigator.mediaDevices.getDisplayMedia({
+      video: { displaySurface: "browser" }
+    });
+  } catch (err) {
+    if (isDismissal(err)) return null;
+    throw err;
+  }
+  try {
+    const video = document.createElement("video");
+    video.muted = true;
+    video.playsInline = true;
+    video.srcObject = stream;
+    await waitForMetadata(video);
+    await video.play();
+    const { videoWidth, videoHeight } = video;
+    if (!videoWidth || !videoHeight) {
+      throw new Error(
+        "[foir] the captured stream reported no dimensions, so there is no frame to draw. This is the browser ending the capture before the first frame arrived \u2014 retry it."
+      );
+    }
+    const scale = videoWidth > maxWidth ? maxWidth / videoWidth : 1;
+    const width = Math.round(videoWidth * scale);
+    const height = Math.round(videoHeight * scale);
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      throw new Error(
+        "[foir] this browser gave no 2d canvas context, so the captured frame cannot be encoded. Nothing was uploaded."
+      );
+    }
+    ctx.drawImage(video, 0, 0, width, height);
+    video.srcObject = null;
+    const dataUrl = canvas.toDataURL(CAPTURE_MIME_TYPE, quality);
+    return {
+      blob: dataUrlToBlob(dataUrl),
+      dataUrl,
+      width,
+      height,
+      mimeType: CAPTURE_MIME_TYPE
+    };
+  } finally {
+    for (const track of stream.getTracks()) track.stop();
+  }
+}
+function isDismissal(err) {
+  const name = err?.name;
+  return name === "NotAllowedError" || name === "AbortError";
+}
+function waitForMetadata(video) {
+  if (video.readyState >= 1) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    video.addEventListener("loadedmetadata", () => resolve(), { once: true });
+    video.addEventListener(
+      "error",
+      () => reject(
+        new Error("[foir] the captured stream failed to load before a frame could be read")
+      ),
+      { once: true }
+    );
+  });
+}
+function dataUrlToBlob(dataUrl) {
+  const comma = dataUrl.indexOf(",");
+  const header = comma === -1 ? "" : dataUrl.slice(0, comma);
+  if (comma === -1 || !header.includes(";base64")) {
+    throw new Error(
+      `[foir] the canvas produced a data URL this build cannot decode (${header || "no header"}). Expected a base64 data URL.`
+    );
+  }
+  const binary = atob(dataUrl.slice(comma + 1));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  const mimeType = header.slice("data:".length, header.indexOf(";"));
+  return new Blob([bytes], { type: mimeType || CAPTURE_MIME_TYPE });
+}
 export {
   BlurhashCanvas,
   DEFAULT_VARIANT_TIERS,
   ProgressiveMedia,
+  captureFoirScreen,
   cropAspectRatio,
   effectiveImageDimensions,
+  isFoirScreenCaptureSupported,
   toProgressiveImage,
   toProgressiveVideo,
   useProgressiveLoad