@journeeze/sdk 0.0.0-stage → 0.1.0-rc.2

package/dist/types/widget/outbox.d.ts

@@ -0,0 +1,69 @@
+import { CollectorError } from "../wire";
+import type { SubmitFeedbackRequest } from "../types";
+/** Stored feedback older than this is stale and is dropped when claimed (§9). */
+export declare const OUTBOX_TTL_MS: number;
+export type Outcome = "sent" | "queued" | "dropped";
+export interface OutboxDeps {
+    send(request: SubmitFeedbackRequest): Promise<void>;
+    storage: Storage | undefined;
+    storageKey: string;
+    /** Which reviewer queued the items ({@link ownerTag}); only matching items are claimed. */
+    owner: string;
+    /** Scheduling seam for tests. */
+    schedule?: (fn: () => void, ms: number) => unknown;
+    cancel?: (handle: unknown) => void;
+    /** Called when an item is dropped as permanently refused. */
+    onDropped?: (error: CollectorError) => void;
+    /** The signed-in user (opaque id) an item is stored under, kept with it for attribution (J6). */
+    user?: () => string | undefined;
+    /** Clock seam for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+export declare function backoffMs(attempt: number): number;
+export declare function isPermanent(error: unknown): error is CollectorError;
+export declare class Outbox {
+    private readonly deps;
+    private items;
+    private inFlight;
+    private attempt;
+    private flushing;
+    private timer;
+    private disposed;
+    private readonly schedule;
+    private readonly cancel;
+    private readonly now;
+    constructor(deps: OutboxDeps);
+    get size(): number;
+    /** Queues and flushes; resolves once this item was sent, dropped, or left queued for retry. */
+    enqueue(request: SubmitFeedbackRequest): Promise<Outcome>;
+    /** Queues without sending (used while the page is being hidden). */
+    stash(request: SubmitFeedbackRequest): void;
+    /** Sends queued items in order. One flush at a time; a pending retry timer is replaced. */
+    flush(): Promise<void>;
+    /** Hands unsent items to storage (appending to what is there) and forgets them here. */
+    persist(): void;
+    /** Takes over this reviewer's items stored by earlier pages (this or another tab). Items of
+     *  another reviewer stay stored: they are never sent under the wrong reviewer's token. */
+    claim(): void;
+    /** Stops sending and stores what is unsent so a later widget can deliver it. */
+    dispose(): void;
+    private add;
+    private drain;
+    /**
+     * Stored items older than {@link OUTBOX_TTL_MS} are dropped (contract §9). An item without a
+     * time was queued by a v0 SDK before the upgrade: it is sent once rather than lost.
+     */
+    private fresh;
+    private remove;
+    private read;
+}
+/**
+ * Non-reversible tag of the reviewer token (FNV-1a, 32 bits) so stored items are claimed only
+ * by the same reviewer. 32 bits of a 256-bit token reveal nothing usable; "" means anonymous.
+ */
+export declare function ownerTag(token: string | undefined): string;
+/**
+ * Logout (contract §8, v1.1): removes this owner's stored items from storage now, whatever happens
+ * next, and returns their requests (those still within {@link OUTBOX_TTL_MS}) to be sent once.
+ */
+export declare function takeOwned(storage: Storage | undefined, storageKey: string, owner: string, now?: number): SubmitFeedbackRequest[];

package/dist/types/widget/styles.d.ts

@@ -0,0 +1 @@
+export declare const CSS = "\n:host { all: initial; }\n.jz {\n  --jz-canvas:#F7F7F5; --jz-surface:#FFFFFF; --jz-raised:#F0F0EC; --jz-ink:#1D2024; --jz-muted:#5D636B;\n  --jz-faint:#8A9099; --jz-rule:rgb(29 32 36 / 12%); --jz-accent:#3D63C9; --jz-accent-ink:#FFFFFF;\n  --jz-accent-soft:rgb(61 99 201 / 10%); --jz-polished:#2F7D4F; --jz-broken:#B42318; --jz-confused:#6E4FC2;\n  --jz-shadow:0 1px 3px rgb(0 0 0 / 12%);\n  font: 400 13px/1.45 Inter, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  color: var(--jz-ink); -webkit-font-smoothing: antialiased;\n}\n@media (prefers-color-scheme: dark) {\n  .jz { --jz-canvas:#111316; --jz-surface:#181B1F; --jz-raised:#20242A; --jz-ink:#E8EAED; --jz-muted:#A3A9B2;\n    --jz-faint:#6F7680; --jz-rule:rgb(232 234 237 / 12%); --jz-accent:#7F9CF0; --jz-accent-ink:#111316;\n    --jz-accent-soft:rgb(127 156 240 / 14%); --jz-confused:#A48BEA; --jz-polished:#5DBB84; }\n}\n.jz *, .jz *::before, .jz *::after { box-sizing: border-box; }\n/* Zero specificity: a component's own colour (.toggle, .primary, ...) must always win. */\n:where(.jz button) { font: inherit; color: inherit; cursor: pointer; }\n.jz :focus-visible { outline: 2px solid var(--jz-accent); outline-offset: 2px; }\n.mono { font-family: \"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, monospace; }\n.sr { position:absolute; width:1px; height:1px; overflow:hidden; clip:rect(0 0 0 0); white-space:nowrap; }\n\n.toggle { position:fixed; right:32px; bottom:32px; z-index:2147483646; height:44px; padding:0 16px; display:flex; align-items:center;\n  gap:8px; border:0; border-radius:999px; background:#1D2024; color:#FFFFFF; box-shadow:var(--jz-shadow); font-weight:500; }\n.toggle .dot { width:8px; height:8px; border-radius:50%; background:var(--jz-polished); }\n.toggle .exit { color:#8A9099; }\n.toggle:hover .exit { color:#FFFFFF; }\n\n.layer { position:fixed; inset:0; z-index:2147483640; pointer-events:none; }\n.hl { position:fixed; display:none; outline:1px solid var(--jz-accent); outline-offset:-1px; border-radius:2px; }\n.hl.masked { outline:1px dashed var(--jz-faint);\n  background:repeating-linear-gradient(45deg, rgb(138 144 153 / 10%) 0 4px, rgb(138 144 153 / 20%) 4px 8px); }\n.tag { position:absolute; left:0; top:-18px; padding:1px 6px; border-radius:2px; background:var(--jz-accent); color:#FFFFFF;\n  font-size:10px; line-height:16px; white-space:nowrap; max-width:280px; overflow:hidden; text-overflow:ellipsis; }\n.hl.masked .tag { background:var(--jz-muted); text-transform:uppercase; letter-spacing:.06em; }\n.pin { position:fixed; width:24px; height:24px; margin:-12px 0 0 -12px; border-radius:50%; display:flex; align-items:center;\n  justify-content:center; background:var(--jz-accent); color:#FFFFFF; font-size:12px; font-weight:500; box-shadow:var(--jz-shadow); }\n\n.pop, .sheet, .checkin, .toast { position:fixed; z-index:2147483645; background:var(--jz-surface); color:var(--jz-ink);\n  border:1px solid var(--jz-rule); box-shadow:var(--jz-shadow); }\n.pop { width:400px; max-width:calc(100vw - 32px); max-height:calc(100vh - 32px); overflow:auto; padding:24px; border-radius:10px;\n  animation: jz-in 180ms ease-out; }\n@keyframes jz-in { from { opacity:0; transform:translateY(4px); } to { opacity:1; transform:none; } }\n.pop-head { display:flex; align-items:center; justify-content:space-between; gap:8px; margin-bottom:20px; }\n.pop h2 { margin:0; font-size:14px; font-weight:500; }\n.close { width:32px; height:32px; display:flex; align-items:center; justify-content:center; border:0; border-radius:6px;\n  background:transparent; color:var(--jz-faint); }\n.close:hover { color:var(--jz-ink); }\n.chips { display:flex; flex-wrap:wrap; gap:8px; margin-bottom:20px; }\n.chip { display:inline-flex; align-items:center; gap:4px; padding:2px 8px; border-radius:999px; background:var(--jz-raised);\n  color:var(--jz-muted); font-size:11px; }\n.reactions { display:flex; border:1px solid var(--jz-rule); border-radius:8px; overflow:hidden; margin-bottom:20px; }\n.reaction { flex:1; min-height:56px; display:flex; flex-direction:column; align-items:center; justify-content:center; gap:4px;\n  padding:12px 4px; border:0; border-right:1px solid var(--jz-rule); background:transparent; color:var(--jz-muted); }\n.reaction:last-child { border-right:0; }\n.reaction:hover { background:var(--jz-canvas); }\n.reaction span { font-size:10px; font-weight:500; }\n.reaction[data-r=\"confused\"] { color:var(--jz-confused); }\n.reaction[aria-checked=\"true\"] { background:var(--jz-accent-soft); color:var(--jz-accent); }\n.reaction[data-r=\"confused\"][aria-checked=\"true\"] { background:rgb(110 79 194 / 10%); color:var(--jz-confused); }\n.comment { display:block; width:100%; height:112px; padding:16px; margin-bottom:20px; resize:none; border:1px solid var(--jz-rule);\n  border-radius:8px; background:var(--jz-surface); color:var(--jz-ink); font:inherit; }\n.comment::placeholder { color:var(--jz-faint); }\n.comment:focus { outline:none; box-shadow:0 0 0 1px var(--jz-accent); }\n.foot { display:flex; align-items:center; justify-content:space-between; gap:12px; }\n.shot { display:flex; align-items:center; gap:12px; min-width:0; }\n.thumb { flex:none; width:80px; height:48px; border-radius:8px; border:1px solid var(--jz-rule); background:var(--jz-canvas);\n  overflow:hidden; display:flex; align-items:center; justify-content:center; color:var(--jz-faint); font-size:8px; }\n.thumb img { width:100%; height:100%; object-fit:cover; }\n.thumb.hatch { background:repeating-linear-gradient(45deg, rgb(138 144 153 / 10%) 0 4px, rgb(138 144 153 / 20%) 4px 8px); }\n.shot-open { display:block; width:100%; height:100%; padding:0; border:0; background:transparent; }\n.optout-row { display:flex; align-items:center; gap:8px; margin-bottom:16px; color:var(--jz-muted); font-size:12px; }\n.optout-row[hidden] { display:none; }\n.note { font-size:11px; color:var(--jz-faint); line-height:1.3; }\n.shot-full { position:fixed; inset:0; z-index:2147483647; display:flex; align-items:center; justify-content:center; padding:24px; background:rgb(0 0 0 / 72%); }\n.shot-full img { max-width:100%; max-height:100%; object-fit:contain; border-radius:6px; background:var(--jz-surface); }\n.shot-full .close { position:absolute; top:16px; right:16px; background:var(--jz-surface); color:var(--jz-ink); }\n.primary { min-height:44px; padding:0 24px; border:0; border-radius:8px; background:var(--jz-accent); color:var(--jz-accent-ink); font-weight:500; }\n.primary:disabled { opacity:.45; cursor:not-allowed; }\n.secondary { min-height:44px; padding:0 16px; border:1px solid var(--jz-rule); border-radius:6px; background:transparent;\n  color:var(--jz-muted); font-weight:500; }\n\n.sheet { left:32px; bottom:32px; width:340px; max-width:calc(100vw - 32px); padding:24px; border-radius:10px; }\n.sheet h2 { display:flex; align-items:center; gap:8px; margin:0 0 12px; font-size:14px; font-weight:500; }\n.sheet h2 svg { color:var(--jz-accent); }\n.sheet p { margin:0 0 12px; color:var(--jz-muted); line-height:1.6; }\n.sheet ul { margin:0 0 20px; padding-left:18px; color:var(--jz-muted); }\n.row { display:flex; gap:8px; }\n.row > * { flex:1; }\n\n.checkin { right:32px; bottom:140px; display:flex; align-items:center; gap:8px; padding:8px 8px 8px 16px; border-radius:10px; }\n.checkin .secondary { min-height:36px; }\n.toast { right:32px; bottom:88px; padding:10px 16px; border-radius:10px; }\n.toast.err { border-color:var(--jz-broken); }\n\n@media (max-width: 479px) {\n  .toggle { right:24px; bottom:24px; height:48px; padding:0 20px; background:var(--jz-accent); color:var(--jz-accent-ink); }\n  .toggle .dot { background:var(--jz-accent-ink); }\n  .toggle .exit { color:inherit; opacity:.8; }\n  .pop { left:0 !important; right:0; top:auto !important; bottom:0; width:auto; max-width:none; max-height:85vh;\n    border-radius:16px 16px 0 0; border-width:1px 0 0; padding:12px 24px 34px; }\n  .pop::before { content:\"\"; display:block; width:48px; height:4px; margin:0 auto 16px; border-radius:999px; background:var(--jz-raised); }\n  .chip { border-radius:4px; border:1px solid var(--jz-rule); }\n  .reactions { display:grid; grid-template-columns:repeat(4, 1fr); gap:12px; border:0; overflow:visible; }\n  .reaction { border:1px solid var(--jz-rule); border-radius:8px; padding:16px 4px; }\n  .reaction:last-child { border-right:1px solid var(--jz-rule); }\n  .reaction[aria-checked=\"true\"] { border:2px solid var(--jz-accent); }\n  .reaction span { font-size:11px; }\n  .foot { flex-direction:column; align-items:stretch; }\n  .foot .primary { width:100%; min-height:52px; font-size:15px; }\n  .sheet { left:16px; right:16px; bottom:16px; width:auto; }\n  .toast { left:16px; right:16px; bottom:84px; }\n  .checkin { left:16px; right:16px; bottom:136px; }\n}\n@media (prefers-reduced-motion: reduce) {\n  .jz *, .jz *::before, .jz *::after { animation-duration:1ms !important; transition-duration:1ms !important; }\n}\n";

package/dist/types/widget.d.ts

@@ -0,0 +1,27 @@
+import type { WidgetModule } from "./loader";
+import { type JourneezeContext, type WireFeedbackContext } from "./types";
+export { maskedSnapshotSvg } from "./widget/capture";
+/**
+ * The PUT target for a screenshot: `uploadUrl` is a path relative to the collector endpoint
+ * (collector.proto). Image bytes only ever go to the collector's own origin.
+ */
+export declare function uploadTarget(uploadUrl: string, endpoint: string): string | undefined;
+/** Strips empty values; adds the page path and device class the widget derives. */
+export declare function wireContext(ctx: Readonly<JourneezeContext>, href: string, width: number, tflowId?: string): WireFeedbackContext;
+/**
+ * The host's signature over the user id (contract §4, v1.3), only while it is well formed and
+ * unexpired; otherwise the id travels unsigned (sites that require signed identity then treat
+ * the request as anonymous). Fixed into the request when it is written, like the id.
+ */
+export declare function signedIdentity(o: {
+    userIdSig?: string | undefined;
+    userIdExp?: number | undefined;
+    signature?: {
+        sig: string;
+        exp: number;
+    } | "" | undefined;
+}): {
+    userIdSig?: string;
+    userIdExp?: number;
+};
+export declare const mount: WidgetModule["mount"];

package/dist/types/wire.d.ts

@@ -0,0 +1,66 @@
+export declare class CollectorError extends Error {
+    readonly code: string;
+    /** HTTP status of the response (0 when there was none). */
+    readonly status: number;
+    /** The response's `Retry-After`, in milliseconds (C0b §6), when it sent one. */
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: string, message: string, 
+    /** HTTP status of the response (0 when there was none). */
+    status?: number, 
+    /** The response's `Retry-After`, in milliseconds (C0b §6), when it sent one. */
+    retryAfterMs?: number | undefined);
+}
+/** The collector a v1 page talks to when the host names none (C0a §5, C0b §1: direct mode). */
+export declare const DEFAULT_API_HOST = "https://app.journeeze.dev";
+export declare const TIMEOUT_MS = 15000;
+/** `init` plus a timeout signal where the browser supports `AbortSignal.timeout`. */
+export declare function withTimeout(init: RequestInit, ms?: number): RequestInit;
+export interface CallOptions {
+    /** Let the request finish after the page unloads (small bodies only, < 64 KB). */
+    keepalive?: boolean;
+}
+/**
+ * The collector base URL from the v0 `endpoint` option: an explicit (relative or absolute)
+ * endpoint is resolved against the page; without one, v1 talks to the Journeeze collector
+ * directly ({@link DEFAULT_API_HOST}, C0a §5 "Change [J3c]"). A v0 host that relied on its own
+ * same-origin proxy without setting `endpoint` must now set `apiHost: location.origin`.
+ */
+export declare function resolveEndpoint(endpoint: string | undefined, base?: string): string;
+/** Whether `endpoint` is another origin than the page's (direct mode: CORS rules apply). */
+export declare function isCrossOrigin(endpoint: string, page?: string): boolean;
+/** The content type of every direct-mode body (C0b §2.1): CORS-safelisted, UTF-8. */
+export declare const TEXT_PLAIN = "text/plain;charset=UTF-8";
+/** The unary RPC URL under `endpoint`. */
+export declare function rpcUrl(endpoint: string, method: string): string;
+/**
+ * The request headers of a unary call: direct mode sends only `text/plain` (a simple request, no
+ * preflight); a help read's `If-None-Match` is added in both modes (that one read preflights,
+ * and the preflight is cached for two hours). Same origin keeps Connect JSON.
+ */
+export declare function unaryHeaders(endpoint: string, etag?: string): Record<string, string>;
+/** No wait (backoff or `Retry-After`) is longer than 60 s (C0b §6). */
+export declare const RETRY_CAP_MS = 60000;
+/** `Retry-After` (whole seconds or an HTTP date) in milliseconds, capped at 60 s (C0b §6). */
+export declare function retryAfterMs(header: string | null, now?: number): number | undefined;
+export declare function callCollector<Res>(endpoint: string, method: string, body: unknown, fetchImpl?: typeof fetch, opts?: CallOptions): Promise<Res>;
+/** A help read (`GetHelpIndex`, `GetGuide`): fresh data with its ETag, or "unchanged". */
+export type Revalidated<Res> = {
+    notModified: false;
+    value: Res;
+    etag?: string;
+} | {
+    notModified: true;
+};
+/**
+ * A read-only collector call that revalidates: sends `If-None-Match` with a previous ETag and
+ * returns `notModified` on `304`. Same rules as {@link callCollector}. Browsers do not cache
+ * POST responses: keep the last value in memory for the response's `max-age`, then revalidate.
+ */
+export declare function callCollectorRevalidating<Res>(endpoint: string, method: string, body: unknown, etag: string | undefined, fetchImpl?: typeof fetch): Promise<Revalidated<Res>>;
+/** A guide asset path (relative to the collector endpoint) as an absolute URL, or `undefined`. */
+export declare function assetUrl(endpoint: string, path: string | undefined): string | undefined;
+/**
+ * Connect code for an HTTP error without a Connect body (proxies, load balancers, framework
+ * rejections). A bare 404 is treated as transient (a deploy or a proxy), never as permanent.
+ */
+export declare function codeForStatus(status: number): string;